edm C. Eckel Internet-Draft Cisco Systems Intended status: Informational 9 July 2021 Expires: 10 January 2022 Find Code Related to an Internet-Draft or RFC draft-eckel-edm-find-code-00 Abstract 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 to find such code. Discussion Venues This note is to be removed before publishing as an RFC. Discussion of this document takes place on the Evolvability, Deployability, & Maintainability mailing list (edm@iab.org), which is archived at https://mailarchive.ietf.org/arch/browse/edm/. Source for this draft and an issue tracker can be found at https://github.com/eckelcu/draft-eckel-edm-find-code. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at https://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on 10 January 2022. Copyright Notice Copyright (c) 2021 IETF Trust and the persons identified as the document authors. All rights reserved. Eckel Expires 10 January 2022 [Page 1] Internet-Draft find-code July 2021 This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/ license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Existing IETF Processes and Procedures . . . . . . . . . . . 3 2.1. Implementation Status . . . . . . . . . . . . . . . . . . 3 2.2. GitHub . . . . . . . . . . . . . . . . . . . . . . . . . 4 2.3. Hackathon . . . . . . . . . . . . . . . . . . . . . . . . 4 3. Proposal . . . . . . . . . . . . . . . . . . . . . . . . . . 4 3.1. Datatracker . . . . . . . . . . . . . . . . . . . . . . . 5 3.2. GitHub Repository . . . . . . . . . . . . . . . . . . . . 5 3.3. README . . . . . . . . . . . . . . . . . . . . . . . . . 5 3.4. Implementation Status . . . . . . . . . . . . . . . . . . 6 3.5. Errata . . . . . . . . . . . . . . . . . . . . . . . . . 6 4. Implementation Status . . . . . . . . . . . . . . . . . . . . 6 5. Security Considerations . . . . . . . . . . . . . . . . . . . 6 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 7. Informative References . . . . . . . . . . . . . . . . . . . 6 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 7 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 8 Eckel Expires 10 January 2022 [Page 2] Internet-Draft find-code July 2021 1. 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 (https://github.com/), 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) (https://www.ietf.org/standards/ids/). 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 is potentially of interest and beneficial to people contributing to the definition, implementation, or deployment of an existing or evolving IETF standard. This document provides a set of practices make it easier to identify and to find such code. 2. 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 (https://www.ietf.org/tao.html). The existence of multiple independently developed and interoperable implementations was explicitly required by [RFC1264] 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. 2.1. 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 [RFC7942]. The goal of this section is to allow the read to assign due consideration to I-Ds that have the 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. Eckel Expires 10 January 2022 [Page 3] Internet-Draft find-code July 2021 2.2. GitHub The IETF chartered the GitHub Integration and Tooling (GIT) (https://datatracker.ietf.org/wg/git/about/) working group to establish and document practices and policies for use of GitHub by working groups for managing their work. This resulted in [RFC8874], which provides a set of guidelines for working groups that choose to use GitHub for their work, and [RFC8875], 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 them. 2.3. Hackathon The IETF Hackathon [I-D.ietf-shmoo-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. 3. 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. Eckel Expires 10 January 2022 [Page 4] Internet-Draft find-code July 2021 3.1. Datatracker The IETF Datatracker (https://datatracker.ietf.org/) supports the association of "Additional Resources" with a "Document" (e.g., an I-D or RFC) or a "Group" (e.g., working group (https://datatracker.ietf.org/wg/), research group (https://datatracker.ietf.org/rg/)). An "Additional Resource" can be, among others things, a GitHub Organization (https://docs.github.com/en/organizations) or a GitHub Repository (https://docs.github.com/en/github/getting-started-with- github/quickstart/create-a-repo#create-a-repository). It is recommended that this Datatracker mechanism be used to associate an appropriate GitHub organization and repository with an I-D. Ideally these are setup per the guidelines in [RFC8874] and [RFC8875]. 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 the I-D using the "github_org" tag. A GitHub repository is associated with the I-D using the "github_repo" tag. 3.2. GitHub Repository A GitHub repository should be setup for an I-D as outlined in Section 3.2 of RFC 8874 (https://www.rfc-editor.org/rfc/ rfc8874.html#section-3.2). The i-d-template (https://github.com/martinthomson/i-d-template) can be used to get started. It provides useful features, including integration with the Datatracker. The resulting repository should be associated with the I-D using the Datatracker "github_repo" tag. This should 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. 3.3. README The GitHub repository associated with the I-D should include a README (https://docs.github.com/en/github/creating-cloning-and-archiving- repositories/creating-a-repository-on-github/about-readmes). 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 Eckel Expires 10 January 2022 [Page 5] Internet-Draft find-code July 2021 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 (https://docs.github.com/en/communities/) within the GitHub repository or the GitHub organization associated with the I-D. The QUIC WG's Implementations wiki (https://github.com/quicwg/base-drafts/wiki/Implementations) is an example. 3.4. Implementation Status An Implementation Status section, as defined [RFC7942], should be added to an I-D. It should include any GitHub organization or GitHub repository associated with the I-D. 3.5. 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 is likely to have been removed. Any GitHub organization or GitHub repository associated with the RFC should be made available as inline errata (https://mailarchive.ietf.org/arch/msg/edm/ ku3cd5xTla7tbtohVYWWW7-XTIg/). 4. Implementation Status The practices proposed in this document are followed by draft-ietf- shmoo-hackathon (https://datatracker.ietf.org/doc/draft-ietf-shmoo- hackathon/). 5. Security Considerations TBD. 6. IANA Considerations This document has no IANA actions. 7. Informative References [I-D.ietf-shmoo-hackathon] Eckel, C., "Running an IETF Hackathon", Work in Progress, Internet-Draft, draft-ietf-shmoo-hackathon-01, 9 July 2021, . Eckel Expires 10 January 2022 [Page 6] Internet-Draft find-code July 2021 [RFC1264] Hinden, R., "Internet Engineering Task Force Internet Routing Protocol Standardization Criteria", RFC 1264, DOI 10.17487/RFC1264, October 1991, . [RFC7942] Sheffer, Y. and A. Farrel, "Improving Awareness of Running Code: The Implementation Status Section", BCP 205, RFC 7942, DOI 10.17487/RFC7942, July 2016, . [RFC8874] Thomson, M. and B. Stark, "Working Group GitHub Usage Guidance", RFC 8874, DOI 10.17487/RFC8874, August 2020, . [RFC8875] Cooper, A. and P. Hoffman, "Working Group GitHub Administration", RFC 8875, DOI 10.17487/RFC8875, August 2020, . Acknowledgments Vijay Gurbani started (https://mailarchive.ietf.org/arch/msg/ edm/1AV0yGy5cetLjmP6aOu0xyD2kHE/) the discussion that inspired this effort. Robert Sparks highlighted a datatracker mechanism (https://mailarchive.ietf.org/arch/msg/wgchairs/DA- fWpq_nsy_5kPhJEheBlyaaqI/) 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 (https://github.com/martinthomson/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 (https://mailarchive.ietf.org/arch/msg/edm/ ku3cd5xTla7tbtohVYWWW7-XTIg/) 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 (https://mailarchive.ietf.org/arch/msg/edm/ ku3cd5xTla7tbtohVYWWW7-XTIg/). Mark Nottingham provided an illustrative examples of how the QUIC (https://github.com/quicwg/base-drafts/wiki/Implementations) working group uses wiki pages to track early implementations. Eckel Expires 10 January 2022 [Page 7] Internet-Draft find-code July 2021 Many other people shared thoughts on the email lists for WG Chairs (https://mailarchive.ietf.org/arch/browse/wgchairs/) and EDM (https://mailarchive.ietf.org/arch/browse/edm/) about how to make it easier to find code. These helped shape the practices outlined in this document. Author's Address Charles Eckel Cisco Systems United States of America Email: eckelcu@cisco.com Eckel Expires 10 January 2022 [Page 8]