Find Code Related to an Internet-Draft or RFC
draft-eckel-edm-find-code-04

edm                                                             C. Eckel
Internet-Draft                                             Cisco Systems
Intended status: Best Current Practice                   22 January 2024
Expires: 25 July 2024

             Find Code Related to an Internet-Draft or RFC
                      draft-eckel-edm-find-code-04

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 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 IAB Program 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 25 July 2024.

Eckel                     Expires 25 July 2024                  [Page 1]
Internet-Draft                  find-code                   January 2024

Copyright Notice

   Copyright (c) 2024 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   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 Revised BSD License text as
   described in Section 4.e of the Trust Legal Provisions and are
   provided without warranty as described in the Revised BSD License.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
   2.  Existing IETF Processes and Procedures  . . . . . . . . . . .   3
     2.1.  Implementation Status . . . . . . . . . . . . . . . . . .   3
     2.2.  GitHub  . . . . . . . . . . . . . . . . . . . . . . . . .   3
     2.3.  Hackathon . . . . . . . . . . . . . . . . . . . . . . . .   4
   3.  Proposal  . . . . . . . . . . . . . . . . . . . . . . . . . .   4
     3.1.  GitHub Repository . . . . . . . . . . . . . . . . . . . .   4
     3.2.  README  . . . . . . . . . . . . . . . . . . . . . . . . .   5
     3.3.  Datatracker . . . . . . . . . . . . . . . . . . . . . . .   5
       3.3.1.  Permissions . . . . . . . . . . . . . . . . . . . . .   6
       3.3.2.  Guidance  . . . . . . . . . . . . . . . . . . . . . .   6
     3.4.  Implementation Status . . . . . . . . . . . . . . . . . .   6
     3.5.  Inline Errata . . . . . . . . . . . . . . . . . . . . . .   7
     3.6.  Known Limitations . . . . . . . . . . . . . . . . . . . .   7
   4.  Implementation Status . . . . . . . . . . . . . . . . . . . .   7
   5.  Security Considerations . . . . . . . . . . . . . . . . . . .   8
   6.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .   8
   7.  Informative References  . . . . . . . . . . . . . . . . . . .   8
   Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . .   8
   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .   9

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,

Eckel                     Expires 25 July 2024                  [Page 2]
Internet-Draft                  find-code                   January 2024

   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.

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 in [RFC7942].  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.

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.

Eckel                     Expires 25 July 2024                  [Page 3]
Internet-Draft                  find-code                   January 2024

   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.

2.3.  Hackathon

   The IETF Hackathon [RFC9311] 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.

3.1.  GitHub Repository

   A GitHub repository (https://docs.github.com/en/github/getting-
   started-with-github/quickstart/create-a-repo#create-a-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 (see Section 3.3).  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
   (https://docs.github.com/en/organizations/collaborating-with-groups-
   in-organizations/about-organizations).  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:

Eckel                     Expires 25 July 2024                  [Page 4]
Internet-Draft                  find-code                   January 2024

   *  IETF HTTP Working Group (https://github.com/httpwg)

   *  IETF QUIC Working Group (https://github.com/quicwg)

   *  Internet Architecture Board (https://github.com/intarchboard)

3.2.  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
   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 Working Group's Implementations wiki
   (https://github.com/quicwg/base-drafts/wiki/Implementations) is an
   example.

3.3.  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 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 [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 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.

Eckel                     Expires 25 July 2024                  [Page 5]
Internet-Draft                  find-code                   January 2024

3.3.1.  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 (mailto:support@ietf.org).

3.3.2.  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.

3.4.  Implementation Status

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

Eckel                     Expires 25 July 2024                  [Page 6]
Internet-Draft                  find-code                   January 2024

3.5.  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 (https://mailarchive.ietf.org/arch/msg/edm/
   ku3cd5xTla7tbtohVYWWW7-XTIg/).  An example of this is RFC 3261 with
   inline errata (https://www.rfc-editor.org/rfc/inline-errata/
   rfc3261.html).

3.6.  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 (https://www.ietf.org/about/groups/tools/)
         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 (https://rfc-
         annotations.research.icann.org/) 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 Section 3.2), 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.

4.  Implementation Status

   The practices proposed in this document are followed by [RFC9311].

Eckel                     Expires 25 July 2024                  [Page 7]
Internet-Draft                  find-code                   January 2024

5.  Security Considerations

   TBD.

6.  IANA Considerations

   This document has no IANA actions.

7.  Informative References

   [RFC1264]  Hinden, R., "Internet Engineering Task Force Internet
              Routing Protocol Standardization Criteria", RFC 1264,
              DOI 10.17487/RFC1264, October 1991,
              <https://www.rfc-editor.org/rfc/rfc1264>.

   [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,
              <https://www.rfc-editor.org/rfc/rfc7942>.

   [RFC8874]  Thomson, M. and B. Stark, "Working Group GitHub Usage
              Guidance", RFC 8874, DOI 10.17487/RFC8874, August 2020,
              <https://www.rfc-editor.org/rfc/rfc8874>.

   [RFC8875]  Cooper, A. and P. Hoffman, "Working Group GitHub
              Administration", RFC 8875, DOI 10.17487/RFC8875, August
              2020, <https://www.rfc-editor.org/rfc/rfc8875>.

   [RFC9311]  Eckel, C., "Running an IETF Hackathon", RFC 9311,
              DOI 10.17487/RFC9311, September 2022,
              <https://www.rfc-editor.org/rfc/rfc9311>.

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.

Eckel                     Expires 25 July 2024                  [Page 8]
Internet-Draft                  find-code                   January 2024

   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 illustrative example of how the QUIC
   (https://github.com/quicwg/base-drafts/wiki/Implementations) 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
   (https://rfc-annotations.research.icann.org/) 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
   (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 25 July 2024                  [Page 9]