Internet DRAFT - draft-daley-rswg-limited-mutability
draft-daley-rswg-limited-mutability
RFC Series Working Group J. Daley
Internet-Draft IETF Administration LLC
Updates: 2026 8153 9280 (if approved) 31 August 2023
Intended status: Informational
Expires: 3 March 2024
Limited Mutability for RFCs
draft-daley-rswg-limited-mutability-01
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:rswg@rfc-
editor.org), which is archived at
https://mailarchive.ietf.org/arch/browse/rswg/.
Daley Expires 3 March 2024 [Page 1]
Internet-Draft Limited Mutability for RFCs August 2023
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.
Copyright Notice
Copyright (c) 2023 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.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Principle of Immutability . . . . . . . . . . . . . . . . 3
1.2. Changed Environment . . . . . . . . . . . . . . . . . . . 3
1.3. The Problems . . . . . . . . . . . . . . . . . . . . . . 4
1.4. Requirements Language . . . . . . . . . . . . . . . . . . 5
2. New Principle . . . . . . . . . . . . . . . . . . . . . . . . 5
2.1. Limited Mutability . . . . . . . . . . . . . . . . . . . 5
2.1.1. Key Definitions . . . . . . . . . . . . . . . . . . . 5
2.1.2. Limitations . . . . . . . . . . . . . . . . . . . . . 6
2.1.3. Correctness and Utility . . . . . . . . . . . . . . . 6
2.1.4. Additional Notes . . . . . . . . . . . . . . . . . . 7
3. Further Considerations . . . . . . . . . . . . . . . . . . . 7
3.1. Use of the current errata system . . . . . . . . . . . . 7
3.2. Operational Implementation . . . . . . . . . . . . . . . 8
3.3. Potential Implications . . . . . . . . . . . . . . . . . 8
Daley Expires 3 March 2024 [Page 2]
Internet-Draft Limited Mutability for RFCs August 2023
4. Updates . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8
6. Security Considerations . . . . . . . . . . . . . . . . . . . 8
7. References . . . . . . . . . . . . . . . . . . . . . . . . . 8
7.1. Normative References . . . . . . . . . . . . . . . . . . 9
7.2. Informative References . . . . . . . . . . . . . . . . . 9
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 9
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 9
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.
Daley Expires 3 March 2024 [Page 3]
Internet-Draft Limited Mutability for RFCs August 2023
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:
* 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.
Daley Expires 3 March 2024 [Page 4]
Internet-Draft Limited Mutability for RFCs August 2023
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.
Daley Expires 3 March 2024 [Page 5]
Internet-Draft Limited Mutability for RFCs August 2023
* 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:
Daley Expires 3 March 2024 [Page 6]
Internet-Draft Limited Mutability for RFCs August 2023
* 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:
* 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.
Daley Expires 3 March 2024 [Page 7]
Internet-Draft Limited Mutability for RFCs August 2023
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:
* Version naming scheme;
* Document name resolution;
* Archival process and archive access requirements;
* New version notification and distribution process.
3.3. 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.
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
Daley Expires 3 March 2024 [Page 8]
Internet-Draft Limited Mutability for RFCs August 2023
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, March 1997,
<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,
May 2017, <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, October 1996,
<https://www.rfc-editor.org/info/rfc2026>.
[RFC8153] Flanagan, H., "Digital Preservation Considerations for the
RFC Series", RFC 8153, DOI 10.17487/RFC8153, April 2017,
<https://www.rfc-editor.org/info/rfc8153>.
[RFC9280] Saint-Andre, P., Ed., "RFC Editor Model (Version 3)",
RFC 9280, DOI 10.17487/RFC9280, June 2022,
<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
Email: jay@staff.ietf.org
Daley Expires 3 March 2024 [Page 9]
