Internet-Draft Limited Mutability for RFCs August 2023
Daley Expires 3 March 2024 [Page]
Workgroup:
RFC Series Working Group
Internet-Draft:
draft-daley-rswg-limited-mutability-01
Updates:
2026 8153 9280 (if approved)
Published:
Intended Status:
Informational
Expires:
Author:
J. Daley
IETF Administration LLC

Limited Mutability for RFCs

Abstract

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 note is to be removed before publishing as an RFC.

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 https://datatracker.ietf.org/doc/draft-daley-rswg-limited-mutability/.

Discussion of this document takes place on the RFC Series Working Group Editorial Stream Working Group mailing list (mailto:[email protected]), which is archived at https://mailarchive.ietf.org/arch/browse/rswg/.

Source for this draft and an issue tracker can be found at https://github.com/JayDaley/draft-daley-rswg-limited-mutability.

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 3 March 2024.

▲

Table of Contents

1. Introduction

1.1. Principle of Immutability

The RFC Series has a long established principle of immutability as documented in Section 2.1 of [RFC2026], Section 2.2 of [RFC8153] and Section 7.6 of [RFC9280].

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.

1.2. 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 [RFC2026] and continued with many subsequent updates to the process. [RFC2026] 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.

1.3. 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:

1.4. 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 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

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

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

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

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

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

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

3. Further Considerations

3.1. 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:

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

3.2. Operational Implementation

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

3.3. Potential Implications

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

4. Updates

If this principle were adopted then that would mean updating [RFC2026] (Section 2.1), [RFC8153] (Section 2.2) and [RFC9280] (Section 7.6) to note that RFCs are now mutable in limited circumstances.

5. IANA Considerations

This document includes no request to IANA.

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

7. References

7.1. Normative References

[RFC2119]
Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, , <https://www.rfc-editor.org/info/rfc2119>.
[RFC8174]
Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, , <https://www.rfc-editor.org/info/rfc8174>.

7.2. Informative References

[RFC2026]
Bradner, S., "The Internet Standards Process -- Revision 3", BCP 9, RFC 2026, DOI 10.17487/RFC2026, , <https://www.rfc-editor.org/info/rfc2026>.
[RFC8153]
Flanagan, H., "Digital Preservation Considerations for the RFC Series", RFC 8153, DOI 10.17487/RFC8153, , <https://www.rfc-editor.org/info/rfc8153>.
[RFC9280]
Saint-Andre, P., Ed., "RFC Editor Model (Version 3)", RFC 9280, DOI 10.17487/RFC9280, , <https://www.rfc-editor.org/info/rfc9280>.

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.

Author's Address

Jay Daley
IETF Administration LLC
1000 N West St, Ste 1200
Wilmington, Delaware 19801
United States of America