Improving Awareness of Running Code: The Implementation Status Section
A lightweight way for Internet-Draft authors to list who has actually implemented their protocol.
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/info/rfc7942>.
@misc{rfc7942,
series = {Request for Comments},
number = 7942,
howpublished = {RFC 7942},
publisher = {RFC Editor},
doi = {10.17487/RFC7942},
url = {https://www.rfc-editor.org/info/rfc7942},
author = {Y. Sheffer and A. Farrel},
title = {{Improving Awareness of Running Code: The Implementation Status Section}},
pagetotal = 8,
year = 2016,
month = jul,
} RFC text
Contents
Internet Engineering Task Force (IETF) Y. Sheffer Request for Comments: 7942 Intuit BCP: 205 A. Farrel Obsoletes: 6982 Juniper Networks Category: Best Current Practice July 2016 ISSN: 2070-1721 Improving Awareness of Running Code: The Implementation Status Section Abstract 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. Status of This Memo This memo documents an Internet Best Current Practice. This document is a product of the Internet Engineering Task Force (IETF). It has been approved for publication by the Internet Engineering Steering Group (IESG). Further information on BCPs is available in Section 2 of RFC 7841. Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at http://www.rfc-editor.org/info/rfc7942. Copyright Notice Copyright (c) 2016 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 (http://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 . . . . . . . . . . . . . . . . . . . . . . . . 2 2. The "Implementation Status" Section . . . . . . . . . . . . . 4 2.1. Introductory Text . . . . . . . . . . . . . . . . . . . . 5 3. Alternative Formats . . . . . . . . . . . . . . . . . . . . . 5 4. Benefits . . . . . . . . . . . . . . . . . . . . . . . . . . 6 5. Security Considerations . . . . . . . . . . . . . . . . . . . 7 6. Informative References . . . . . . . . . . . . . . . . . . . 7 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 8 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 8 1. Introduction Most IETF participants are familiar with the saying "rough consensus and running code" [Tao] and can identify with its pragmatic approach. However, implementation is not a requirement for publication as an RFC. There are many examples of Internet-Drafts containing protocol specifications that have gone through to publication as Proposed Standard RFCs without implementation. Some of them may never get implemented. Over time, a variety of policies have been applied within the IETF to consider running code. In the Routing Area, it used to be a requirement that one or more implementations must exist before an Internet-Draft could be published as a Proposed Standard RFC [RFC1264]. That RFC was later obsoleted and the requirement for implementation was lifted, but each working group was given the authority to impose its own implementation requirements [RFC4794] and at least one working group, Inter-Domain Routing (IDR), continues to require two independent implementations. The hypothesis behind the current document is that there are benefits to the IETF standardization process of producing implementations of protocol specifications before publication as RFCs. These benefits, which include determining that the specification is comprehensible and that there is sufficient interest to implement, are further discussed in Section 4. This document describes a simple mechanism that allows authors of Internet-Drafts to record and publicize the status of known implementations by including an Implementation Status section. The document defines (quite informally) the contents of this section to ensure that the relevant information is included. 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. It is up to the individual working groups to use this information as they see fit, but one result might be the preferential treatment of documents, resulting in them being processed more rapidly. We recommend that the Implementation Status section should be removed from Internet-Drafts before they are published as RFCs. As a result, we do not envisage changes to this section after approval of the document for publication, e.g., the RFC errata process does not apply. 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. The scope of this process is all Internet-Drafts (I-Ds) that contain implementable specifications, whether produced within IETF working groups or outside working groups but intended for IETF consensus. I-Ds published on the Independent Stream are explicitly out of scope. It is expected that the greatest benefit will be seen with Standards Track documents developed within working groups. This process was initially proposed as an experiment in [RFC6982]. That document is now obsoleted, and the process advanced to Best Current Practice. Historically, there have been other ways for experience based on protocol implementations to feed back into the IETF process. Many "implementation reports" have been published, in some cases several years after the protocol was originally published. Providing feedback to published protocols is a related goal, but different from the current document's focus. Two notable examples of published implementation reports are [RFC1369] and [RFC5080]. 2. The "Implementation Status" Section Each Internet-Draft may contain a section entitled "Implementation Status". This section, if it appears, should be located just before the "Security Considerations" section and contain, for each existing implementation, some or all of the following: - The organization responsible for the implementation, if any. - The implementation's name and/or a link to a web page where the implementation or a description of it can be found. - A brief general description. - The implementation's level of maturity: research, prototype, alpha, beta, production, widely used, etc. - Coverage: which parts of the protocol specification are implemented. - Version compatibility: what version/versions of the Internet-Draft are known to be implemented. - Licensing: the terms under which the implementation can be used. For example: proprietary, royalty licensing, freely distributable with acknowledgement (BSD style), freely distributable with requirement to redistribute source (General Public License (GPL) style), and other (specify). - Implementation experience: any useful information the implementers want to share with the community. - Contact information: ideally a person's name and email address, but possibly just a URL or mailing list. - The date when information about this particular implementation was last updated. In addition, this section can contain information about the interoperability of any or all of the implementations, including references to test-case descriptions and interoperability reports, when such exist. Working group chairs and area directors (ADs) are requested to ensure that this section is not used as a marketing venue for specific implementations. Since this information is necessarily time dependent, it is inappropriate for inclusion in a published RFC. The authors should include a note to the RFC Editor requesting that the section be removed before publication. 2.1. Introductory Text The following boilerplate text is proposed to head the Implementation Status section: This section records the status of known implementations of the protocol defined by this specification at the time of posting of this Internet-Draft, and is based on a proposal described in RFC 7942. The description of implementations in this section is intended to assist the IETF in its decision processes in progressing drafts to RFCs. Please note that the listing of any individual implementation here does not imply endorsement by the IETF. Furthermore, no effort has been spent to verify the information presented here that was supplied by IETF contributors. This is not intended as, and must not be construed to be, a catalog of available implementations or their features. Readers are advised to note that other implementations may exist. According to RFC 7942, "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. It is up to the individual working groups to use this information as they see fit". Authors are requested to add a note to the RFC Editor at the top of this section, advising the Editor to remove the entire section before publication, as well as the reference to RFC 7942. 3. Alternative Formats Sometimes it can be advantageous to publish the implementation status separately from the base Internet-Draft, e.g., on the IETF wiki: - When the Implementation Status section becomes too large to be conveniently managed within the document. - When a working group decides to have implementors, rather than authors, keep the status of their implementations current. - When a working group already maintains an active wiki and prefers to use it for this purpose. - If the working group decides that the information is still valuable (and needs to be kept current) after the I-D is published as an RFC, and the Implementation Status section had been removed from it. It is highly desirable for all readers of the Internet-Draft to be made aware of this information. Initially, this can be done by replacing the Implementation Status section's contents with a URL pointing to the wiki. Later, the IETF Tools may support this functionality, e.g., by including such a link in the HTML file of the document, similar to the IPR link. If the implementation status is published separately from the I-D, then this information needs to be openly available without requiring authentication, registration, or access controls if it is to have any useful effects. 4. Benefits Publishing the information about implementations provides the working group with several benefits: - Working group members, chairs, and ADs may use the information provided to help prioritize the progress of I-Ds, e.g., when there are several competing proposals to solve a particular problem. - Similarly, the information is useful when deciding whether the document should be progressed on a different track (individual submission, Experimental, etc.). - Making this information public and an explicit part of WG deliberations will motivate participants to implement protocol proposals, which in turn helps in discovering protocol flaws at an early stage. - Other participants can use the software to evaluate the usefulness of protocol features, its correctness (to some degree), and other properties, such as resilience and scalability. - WG members may choose to perform interoperability testing with known implementations, especially when they are publicly available. - In the case of open source, people may want to study the code to better understand the protocol and its limitations, determine if the implementation matches the protocol specification, and whether the protocol specification has omissions or ambiguities. - And lastly, some protocol features may be hard to understand, and for such features, the mere assurance that they can be implemented is beneficial. We note though that code should never be used in lieu of a clear specification. We do not specify here whether and to what degree working groups are expected to prefer proposals that have "running code" associated with them, over others that do not. Working group chairs are invited to suggest this mechanism to document editors in their working groups, and to draw the attention of their working group participants to Implementation Status sections where they exist. 5. Security Considerations This is a process document; therefore, it does not have a direct effect on the security of any particular IETF protocol. However, better-reviewed protocols are likely to also be more secure. 6. Informative References [RFC1264] Hinden, R., "Internet Engineering Task Force Internet Routing Protocol Standardization Criteria", RFC 1264, DOI 10.17487/RFC1264, October 1991, <http://www.rfc-editor.org/info/rfc1264>. [RFC1369] Kastenholz, F., "Implementation Notes and Experience for the Internet Ethernet MIB", RFC 1369, DOI 10.17487/RFC1369, October 1992, <http://www.rfc-editor.org/info/rfc1369>. [RFC4794] Fenner, B., "RFC 1264 Is Obsolete", RFC 4794, DOI 10.17487/RFC4794, December 2006, <http://www.rfc-editor.org/info/rfc4794>. [RFC5080] Nelson, D. and A. DeKok, "Common Remote Authentication Dial In User Service (RADIUS) Implementation Issues and Suggested Fixes", RFC 5080, DOI 10.17487/RFC5080, December 2007, <http://www.rfc-editor.org/info/rfc5080>. [RFC6982] Sheffer, Y. and A. Farrel, "Improving Awareness of Running Code: The Implementation Status Section", RFC 6982, DOI 10.17487/RFC6982, July 2013, <http://www.rfc-editor.org/info/rfc6982>. [Tao] Hoffman, P., Ed., "The Tao of IETF: A Novice's Guide to the Internet Engineering Task Force", 2012, <http://www.ietf.org/tao.html>. Acknowledgements We would like to thank Stephen Farrell, who reawakened community interest in this topic. Several reviewers provided important input, including Loa Andersson, Dave Crocker, Ned Freed, Joel M. Halpern, Christer Holmberg, Denis Ovsienko, and Curtis Villamizar. This document was originally prepared using the lyx2rfc tool, and we would like to thank Nico Williams, its author. Authors' Addresses Yaron Sheffer Intuit Email: yaronf.ietf@gmail.com Adrian Farrel Juniper Networks Email: adrian@olddog.co.uk
AI ELI5
On this page
§1Why Track Running Code
Many IETF participants know the saying "rough consensus and running code". Yet implementation is not a requirement for publication as an RFC, and some Proposed Standards were published without any implementation. Some may never be implemented.
Policies have varied. The Routing Area once required one or more implementations before a Proposed Standard (RFC 1264). Later that was lifted and each working group could set its own rules (RFC 4794). The Inter-Domain Routing (IDR) working group still requires two independent implementations.
The hypothesis here is that implementing a specification before publication benefits the process, for example by showing it is comprehensible and that there is enough interest to implement it.
Some rulebooks get published before anyone has tried playing the game. This note says it helps to try the game first and write down who did.
§1Scope and Voluntary Use
The process is not mandatory. Authors are encouraged to consider it, and working groups are invited to think about applying it to all their protocol specifications. Working groups decide how to use the information. One result might be that documents are processed more rapidly.
It covers all Internet-Drafts with implementable specifications, whether produced inside working groups or outside them but intended for IETF consensus. Drafts on the Independent Stream are explicitly out of scope. The greatest benefit is expected for Standards Track documents developed within working groups.
The process began as an experiment in RFC 6982, which this document obsoletes, advancing the process to a Best Current Practice.
Nobody is forced to use it. It is an offer to authors, and each group decides how much to care about the answers.
§2The Implementation Status Section
An Internet-Draft may contain a section titled "Implementation Status", placed just before "Security Considerations". For each implementation it may include some or all of: the responsible organization; the name or a link; a brief description; the maturity level (research, prototype, alpha, beta, production, widely used and so on); coverage of the specification; the draft versions implemented; licensing terms; implementation experience; contact information; and the date the entry was last updated.
The section can also cover interoperability, with references to test-case descriptions and reports. Chairs and area directors are asked to make sure it is not used as a marketing venue.
Because the information is time dependent, it is inappropriate in a published RFC. Authors should add a note asking the RFC Editor to remove the section before publication, so the RFC errata process does not apply to it.
Each builder gets a little card: who they are, what they built, how finished it is and how to reach them. The cards are thrown away when the book is printed.
§2.1The Boilerplate Introduction
The RFC proposes boilerplate text to head the section. It says the section records known implementations at the time of posting and is meant to assist the IETF in progressing drafts to RFCs. It states that listing an implementation does not imply endorsement by the IETF, that no effort was spent verifying contributed information, and that it is not a catalog of available implementations.
Authors are also asked to put a note to the RFC Editor at the top of the section, asking that the entire section and the reference to RFC 7942 be removed before publication.
The cards start with a short warning label: we did not check these, and being listed does not mean the IETF approves.
§3Alternative Formats
Sometimes it is better to publish implementation status separately, for example on the IETF wiki. The RFC lists these cases: the section has grown too large to manage in the document; a working group wants implementors rather than authors to keep entries current; a working group already runs an active wiki; or the information stays valuable after the draft becomes an RFC.
Readers of the draft should still be made aware of it, initially by replacing the section's contents with a URL to the wiki. If published separately, the information needs to be openly available without authentication, registration or access controls to have any useful effect.
If the cards pile up, you can keep them on a shared noticeboard instead, as long as anyone can walk up and read them.
§4Benefits
The RFC lists several benefits to a working group. Members, chairs and area directors can use the information to prioritize drafts, for instance when competing proposals exist, or to decide whether a document should move to a different track such as individual submission or Experimental. Making it public motivates participants to implement proposals, which helps find flaws early. Others can use the software to evaluate protocol features, check correctness to some degree, and look at resilience and scalability. They can also test interoperability or, with open source, study the code.
The RFC adds a caution: code should never be used in lieu of a clear specification. It does not say whether or how much working groups should prefer proposals that have running code.
Knowing who built it helps everyone pick the best ideas, find mistakes early and try things out. But the written rules still come first.
§5Security Considerations
This is a process document, so it has no direct effect on the security of any particular IETF protocol. The authors add only that better-reviewed protocols are likely to also be more secure.
This is a rule about paperwork, not about locks, but protocols that more people have tried tend to be safer.