]> IETF Administration LLC

1000 N West St, Ste 1200 Wilmington Delaware 19801 US jay@staff.ietf.org

RFC Editor RFC Series Working Group immutability The environment in which RFCs are produced has changed significantly since the inception of the series: the process for producing RFCs is now a heavyweight process; there is a large and growing set of errata, many with serious implications; and the expectations around the use of RFCs have changed significantly as document technology has evolved. In this new environment, the long-standing principle of immutability of RFCs, prevents the RFC Series from achieving its goals of technical excellence and easily understood documentation. This document addresses that by identifying a possible way forward of a new principle of limited mutability for the RFC Series that allows the publishing of new versions of RFCs in limited circumstances, replacing the principle of immutability. About This Document This document is written by the IETF Executive Director, an employee of the IETF Administration LLC, whose role excludes them from having any direct influence on the Internet standards process. This document is intended as a discussion document for the RSWG about the overall RFC Series, and therefore broader than the Internet standards process, though inevitably it will have an influence on the Internet standards process if adopted. Given that potential, the IETF Chair has given permission for this author to produce this document as a discussion document. Status information for this document may be found at . Discussion of this document takes place on the RFC Series Working Group Editorial Stream Working Group mailing list (), which is archived at . Source for this draft and an issue tracker can be found at .

Introduction

Principle of Immutability The RFC Series has a long established principle of immutability as documented in , and . This principle was entirely appropriate when the series first began. The process for authoring and publishing an RFC was lightweight and, as those initial RFCs were typed up and distributed in hard copy, it was neither practical nor necessary to issue corrected versions. Even after RFCs switched to an electronic format, for many years the process for authoring and publishing an RFC was sufficiently lightweight that any serious error in an RFC could be corrected by publishing a new RFC.

Changed Environment The environment around the RFC Series has gradually transitioned and is now very different in three key aspects:

1. For the bulk of RFCs, the process for authoring and publishing is now intentionally a heavyweight process. This change began most notably with and continued with many subsequent updates to the process. set out some principles that determined the need for a heavier weight process, two of which are particularly relevant here:
   • technical excellence;
   • clear, concise, and easily understood documentation;
2. The collection and verification of errata began in 2000, though not formally documented in an RFC until RFC 7322 in 2014, and the verification process has been refined a number of times since. At the time of writing there are now 2944 verified errata, ranging in seriousness from simple spelling errors through to errors in the text that completely invert the intended meaning. This is in addition to another 2069 reported errata that have been identified as suitable for consideration in future updates of the document.
3. The expectations and technology for managing, distributing and consuming documents, and new versions of documents, has evolved significantly. Of particular note to the IETF is that there is now an increasing push for all technical documents to become more and more like code - computer readable including the semantic structure, and tracked in version control systems. The RFC Series has responded directly to this with the switch to XML as the canonical source publication format for RFCs, and the extensive use of GitHub by authors.

The Problems The RFC Series now faces a number of problems relating to immutability. The first and most serious of these is that there are many published RFCs that are known to contain serious errors and are being actively used by implementers and others who are entirely unaware of this. While there have been experiments in displaying RFCs with inline errata, no serious attempts have been made to ensure that implementers or other consumers of RFCs are not misled by these errors. This current position violates the two principles from RFC 2026 above - RFCs with known serious errors are neither technically excellent nor easily understood. The second is that the use of XML as the canonical source format has created a new “layer” to the RFCs, the markup layer, that has its own set of issues and opportunities including:

• errors in the XML that do not affect the content of the RFC;
• use of XML constructs, features or libraries that become defunct;
• potential for adding new XML markup that enhances the computer readability of an RFC without changing the content;
• errors in the published formats of RFCs that are rendered from the canonical source XML;
• potential for amending/enhancing the rendered formats.

Requirements Language The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here.

New Principle The following new principle is presented as a possible way forward to address these concerns, while avoiding a radical change to the RFC Series with all the implications of such a change.

Limited Mutability The new principle for the RFC Series is limited mutability, which replaces the previous principle of immutability. This principle is stated as follows: With limitations, and solely to correct original errors, or to maintain the utility of the metadata, markup, layout and renderings, of an RFC, a new version of an RFC or a new version of an existing rendering, MAY be published, replacing the previously published RFC or rendering.

Key Definitions The key definitions of terms in this principle are as follows:

• An 'original error is an error in the content that, had it been discovered before the publication of the RFC, would have been corrected by the authors. Original errors are in one of three categories:

  Editorial:

  A spelling, grammar, punctuation, or syntax error that does not affect the technical meaning.

  Transparent:

  A technical error that a reader is likely to detect and understand what the correct intent is, or, even if they do not detect it, will not confuse the reader as to the correct intent.

  Misleading/Confusing:

  A technical error that a reader is unlikely to detect and will confuse or mislead the reader, or, even if they do detect it, the reader will be confused or misled as to the correct intent.

• A new version of an RFC is defined as a new version of the canonical source, where any combination of the content, metadata, markup and layout changes. The nature of the canonical source depends on the specific RFC. For example, for some it is an RFCXML file, for others a plain text file and for others a plain text transcription of a typewritten document.
• A rendering of an RFC is any published format derived from the canonical source.

Limitations The general limitation of this principle is to restrict publication of new versions to the only those absolutely necessary to maintain correctness and utility, which leads to the following more detailed limitations:

• Publishing new versions of an RFC solely for the application of editorial and/or transparent errors SHOULD be avoided. Exceptional circumstances could include a full republication of all RFCs, or an RFC with multiple editorial or transparent errors such that the quality risks the reputation of the series.
• New versions of an RFC MUST NOT be published for an RFC designated as historic or obsolete. New versions of an RFC MAY be published for an RFC whose status is unknown.
• New versions of an RFC or new versions of a rendering of an RFC SHOULD NOT be published so often that it risks undermining the reputation or utility of the series. There may be exceptional circumstances whereby it is agreed that a risk to the reputation of the series is acceptable.
• A new version of a rendering of an RFC, where the canonical source of that RFC has not changed since the last version of the rendering, MUST NOT have any change in content, except to correct a discrepancy in the content between the rendering and the canonical source.
• Publishing a new version of an RFC or a new version of a rendering of an RFC where nothing changes except the version number, SHOULD be avoided. There may be exceptional circumstances where this is necessary.

Correctness and Utility Correctness and utility are measured as follows, though more detailed or more applicable measures may be developed over time:

• The correctness of content SHOULD be measured against the long-standing Internet standards principles of ‘technical excellence’ and ‘easily understood’.
• The utility of metadata, markup, layout and renderings SHOULD be measured against the reasonable expectations of implementers, researchers and other common consumers of RFCs, and the IETF community and RFC Editor function as producers of RFCs.

Additional Notes The following notes are provided to explain certain choices in the development of this principle. A specific minimum time period between publications is intentionally not provided as this may change as expectations of RFC consumers change, and because it would need to be different for different renderings. For example, the HTML or HTML-ised rendering of an RFC could change much more frequently than the PDF rendering while still meeting the limitations above. Under this policy, when one RFC updates another that cannot result in a content change in the updated RFC. Updates do not always specify the precise text to change and even when they do, they rarely provide a clear statement of the new text. It would therefore require an entirely new process to determine the exact text to change, which is out of scope for this document.

Further Considerations

Use of the current errata system Discussions in the RSWG indicate that a number of changes are needed before the information produced by the current errata system can be used to identify the 'original errors' that can be applied under this new principle. These changes include:

• As an erratum may now be used to publish a new version of an RFC:
  • Those reviewing errata need to clearly understand that when conducting their review.
  • More thorough community review of errata is required.
• The errata review process needs to consider the visibility and impact of a technical errata and therefore distinguish betweeen 'Transparent' and 'Misleading/Confusing' errors.

It is out of scope for this document to design a new errata system that incorporates these changes.

Operational Implementation This document intentionally leave several implementation details unspecified as these are best considered operational matters for the RFC Editor to determine:

• Version naming scheme;
• Document name resolution;
• Archival process and archive access requirements;
• New version notification and distribution process.

Potential Implications Adoption of this new principle could to lead to the following:

• There is likely to be an impact on the policies and processes of third-party organisations that archive the RFC Series.
• Authors may be more likely to add less stable references than they do now, with the expectation that these can be replaced if they break.

Updates If this principle were adopted then that would mean updating , and to note that RFCs are now mutable in limited circumstances.

IANA Considerations This document includes no request to IANA.

Security Considerations The implementation of the new principle identified in this document would enhance the security of the Internet by reducing the number of occasions when an implementer is presented with an RFC with serious errors in it.

References Normative References Informative References

Acknowledgements This document was only possible after many conversations with Alexis Rossi, Alice Russo, Brian Carpenter, Jean Mahoney. John Levine, Martin Thomson, Paul Hoffman, Robert Sparks, Sandy Ginoza and Stephen Farrell and email exchanges with Steve Crocker and Scott Bradner.