]> Cisco Systems

United States of America eckelcu@cisco.com

General edm Internet-Draft Code related to existing IETF standards and ongoing standardization efforts may exist and be publicly accessible in many places. This document provides a set of practices to make it easier to identify and find such code. Discussion Venues Discussion of this document takes place on the Evolvability, Deployability, & Maintainability IAB Program mailing list (edm@iab.org), which is archived at . Source for this draft and an issue tracker can be found at .

Introduction Code related to existing IETF standards and ongoing standardization efforts may exist and be publicly accessible in many places. One common place is GitHub, but there are many others. The relationship of the code to corresponding IETF standards efforts may be direct, as in the case of a client or server that supports protocol defined by an Internet-Draft (I-D). It may be indirect, as in a utility that helps analyze network traffic corresponding to this same protocol. The maturity and status of the code may vary considerably, including something written quickly as a proof of concept during a hackathon, a well established and supported implementation, or a legacy project no longer actively developed or maintained. The code must be publicly available, and preferably open source, though other terms of use may exist as well. In all cases, the code may be of interest and helpful to people contributing to the definition, implementation, or deployment of an existing or evolving IETF standard. This document provides a set of practices that make it easier to identify and find such code.

Existing IETF Processes and Procedures The idea that code related to IETF standards is valuable is not new. Most IETF participants are familiar with the phrase "rough consensus and running code" from the IETF Tao. The existence of multiple independently developed and interoperable implementations was explicitly required by for internet standards on routing protocols. Subsequent updates relaxed this requirement, but the value of running code is still appreciated, and several current RFCs define processes and procedures related to running code.

Implementation Status A simple process that allows authors of I-Ds to record the status of known implementations by including an Implementation Status section is defined in . The intent of this section is to allow the reader to assign due consideration to I-Ds that have the added benefit of running code, which may serve as evidence of valuable experimentation and feedback that make the protocols and corresponding documents more mature. However, it is stated that the Implementation Status section should be removed from I-Ds before they are published as RFCs. As a result, the value of the code is limited to that required to develop the standard, and the mechanism does not help find the code once the RFC is published.

GitHub The IETF chartered the GitHub Integration and Tooling (GIT) working group to establish and document practices and policies for use of GitHub by working groups for managing their work. This resulted in , which provides a set of guidelines for working groups that choose to use GitHub for their work, and , which specifies a set of administrative processes and conventions for such working groups. Within the working group, the concept of work is limited to the development of I-Ds that may eventually become RFCs. Any concept of code is limited to that which appears as text within these documents. In many cases, there is additional code that is closely associated with the documents but not contained within them. This code may be of interest to the community of people contributing to the development of the documents or to the implementation or deployment of eventual standards defined by the documents.

Hackathon The IETF Hackathon encourages the IETF community to collaborate on running code related to existing and evolving Internet standards. Each Hackathon has a wiki that provides a brief description of each project. It is common for there to be one of more I-Ds or RFCs associated with each project, and for there to be one or more related code repositories. These resources are often listed on the wiki, but they are documented and shared with project teams in other ways as well. After the Hackathon, the wiki remains available, but the information within it is typically not updated or maintained.

Proposal This section specifies a set of practices that use existing mechanisms to associate code with an I-D or RFC. Following these practices makes it easier for others working with the I-D or RFC to find such code.

GitHub Repository A GitHub repository should be setup for an I-D, as outlined in Section 3.2 of RFC 8874. The i-d-template can be used to get started. It provides useful features, including integration with the Datatracker (see ). The resulting repository should be associated with the I-D using the Datatracker github_repo tag. This may be done even if GitHub is not to be used to collaborate on the I-D. A GitHub repository typically exists within a GitHub organization. This is not always the case (e.g., a repository in a personal GitHub account), and even when it is, the GitHub organization may not be appropriate to associated with the I-D. In the event there is an appropriate GitHub organization, it should be associated with the I-D using the Datatracker github_org tag. Examples of such GitHub organizations are:

• IETF HTTP Working Group
• IETF QUIC Working Group
• Internet Architecture Board

README The GitHub repository associated with the I-D should include a README. The README should include information about the repository, whether or not it is being used to collaborate on the I-D, and any code associated with the I-D. The latter may be achieved by including direct links to such code or by including links to other resources that include information about such code. These resources may be a file, folder, or wiki within the GitHub repository or the GitHub organization associated with the I-D. The QUIC Working Group's Implementations wiki is an example.

Datatracker The IETF Datatracker supports the association of Additional Resources with a Document (e.g., an I-D or RFC) or a Group (e.g., working group, research group). An Additional Resource can be, among other things, a GitHub organization, GitHub repository, or code associated with an I-D or RFC. It is recommended that this Datatracker mechanism be used to associate an appropriate GitHub organization and repository with an I-D. Ideally the organization and repository are setup per the guidelines in and . In the event the working group or research group is not using GitHub, or the I-D has not yet been adopted by the group, another GitHub organization or repository may be used instead. A GitHub organization is associated with an I-D using the github_org tag. A GitHub repository is associated with an I-D using the github_repo tag. It is also recommended that this Datatracker mechanism be used to associate code with an I-D. Code can be associated with an I-D using the related_implementations tag.

Permissions The ability to associate Additional Resources with an I-D is limited to:

• Authors of individual drafts
• Working group chairs of working group drafts
• Working group chairs of RFCs produced by that working group

Additionally, change requests can be sent to the secretariat via support@ietf.org.

Guidance The determination of the appropriateness of Additional Resources associated with an I-D or RFC ultimately lies in the hands of the working group. Any code associated via a related_implementations tag should be:

• helpful to people contributing to the definition, implementation, or deployment of the I-D or RFC to which it is being associated
• publicly available online (e.g., via GitHub or similar)
• licensed under an OSI-approved open source license (other licenses, including proprietary licenses, may be allowed at the discretion of the working group)
• accompanied by clear documentation (e.g., README) on the purpose and state of the code, how to use it, how to contribute to it, and how to get help

Authors of individuals drafts should consider this guidance when adding related_implementations to their individual drafts. The working group and its chairs should review the appropriateness of related_implementations as they would any other content within a working group draft, both when initially adding and periodically as the draft progresses from an I-D to an RFC.

Implementation Status An Implementation Status section, as defined , should be added to an I-D. It should state any GitHub organization or GitHub repository associated with the I-D.

Inline Errata In the event an I-D becomes an RFC, people looking for code are less likely to reference the Datatracker, and the Implementation Status section may have been removed or outdated. Any GitHub organization or GitHub repository associated with the RFC should be made available as inline errata. An example of this is RFC 3261 with inline errata.

Known Limitations Known limitations of this proposal, and ongoing efforts to address them, include the following:

• The ability within the Datatracker to associate Additional Resources with an I-D or RFC is not well known or used.
  • The IETF Tools Team has made the ability to view and edit Additional Resources more prominent in the Datatracker.
  • The functionality is promoted in IETF Hackathons.
• The ability and procedure to submit errata is not well known or used, and errata that is submitted is not always processed in a timely fashion.
  • An experiment with collaborative annotations for RFCs related to DNS has been sponsored by ICANN.
• The GitHub service, a GitHub repository associated with an I-D or RFC, or code referenced in a README (see ), may get deleted or otherwise become unavailable.
  • Collaboration with a code archiving service or creation of an IETF code archiving service could be helpful. Such a service need not have full code history, i.e., snapshots could be sufficient.

Implementation Status The practices proposed in this document are followed by .

Security Considerations TBD.

IANA Considerations This document has no IANA actions.

Informative References This informational RFC presents procedures for creating and documenting Internet standards on routing protocols. These procedures have been established by the Internet Activities Board (IAB) in consultation with the Internet Engineering Steering Group (IESG). This memo provides information for the Internet community. It does not specifiy an Internet standard. This document describes a simple process that allows authors of Internet-Drafts to record the status of known implementations by including an Implementation Status section. This will allow reviewers and working groups to assign due consideration to documents that have the benefit of running code, which may serve as evidence of valuable experimentation and feedback that have made the implemented protocols more mature. This process is not mandatory. Authors of Internet-Drafts are encouraged to consider using the process for their documents, and working groups are invited to think about applying the process to all of their protocol specifications. This document obsoletes RFC 6982, advancing it to a Best Current Practice. This document provides a set of guidelines for working groups that choose to use GitHub for their work. The use of GitHub in IETF working group processes is increasing. This document describes uses and conventions for working groups that are considering starting to use GitHub. It does not mandate any processes and does not require changes to the processes used by current and future working groups not using GitHub. IETF Hackathons encourage the IETF community to collaborate on running code related to existing and evolving Internet standards. This document provides a set of practices that have been used for running IETF Hackathons. These practices apply to Hackathons in which both in-person and remote participation are possible, with adaptations for Hackathons that are online only.

Acknowledgments Vijay Gurbani started the discussion that inspired this effort. Robert Sparks highlighted a datatracker mechanism to add a reference to a GitHub repository or organization using the github_repo or github_org tag, respectively. Martin Thompson created the i-d-template repository can be used to setup a GitHub repository for an I-D. Spencer Dawkins pointed out the RFC editor's ability to inline errata and noted that something similar could be done to point to code. Adam Roach played in important role in enabling the RFC editor's ability to inline errata. Mark Nottingham provided illustrative example of how the QUIC working group uses wiki pages to track early implementations. Yaron Sheffer highlighted limitations with the current errata process and the existence of the ICANN project for collaborative annotations of RFCs related to DNS. Benson Muite highlighted the possibility of repositories getting deleted and the potential value of an archiving solution. Many other people shared thoughts on the email lists for WG Chairs and EDM about how to make it easier to find code. These helped shape the practices outlined in this document.