| Internet-Draft | Format Framework | June 2023 |
| Hoffman | Expires 4 December 2023 | [Page] |
This document updates RFC 7990 by changing the definition of the "canonical format" for RFCs and describing the archival versions of RFCs in more depth.¶
This draft is part of the RFC Series Working Group (RSWG); see https://datatracker.ietf.org/edwg/rswg/documents/. There is a repository for this draft at https://github.com/paulehoffman/draft-rswg-rfc7990-updates. Issues can be raised there, but probably should be on the mailing list instead.¶
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 4 December 2023.¶
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.¶
[RFC7990] defines a framework for how RFCs would be published after that document was published, including new formats and a new canonical format for archiving RFCs. It talks about "the XML file" as if there will only be one XML file for an RFC because this was the expectation at the time [RFC7990] was published.¶
The first RFC to be published using the group of RFCs described in [RFC7990] was [RFC8651], published in October 2019. In the time since then, all published RFCs have followed the general plan from [RFC7990].¶
After extensive experience with publishing RFCs in the XML format, it has been decided that an RFC's XML file can be updated for narrowly limited purposes. This document updates [RFC7990] in that it changes the definition of the canonical format for RFCs and lists the purposes which can cause the RFC Editor to change the contents of the XML file. This document also specifies that older versions of the XML file for an RFC are archived and made available for historical purposes.¶
This document explicitly does not update the other documents referenced in [RFC7990].¶
[[ Jay Daley would like to use "RFCXML" instead of "XML" because we are describing a very specific XML language that is used. ]]¶
Section 3 of [RFC7990] defines the canonical format as:¶
Canonical format: the authorized, recognized, accepted, and archived version of the document¶
The definition of "canonical format" in Section 3 of [RFC7990] is updated to be:¶
Canonical format: the authorized, recognized, accepted, and most recent version of the document published by the RFC Editor¶
[[ Another option: the XML document published by the RFC Editor in the most recent version of the XML format ]]¶
The final XML file produced by the RFC Editor will be considered the canonical format for RFCs; it is the lowest common denominator that holds all the information intended for an RFC.¶
This wording does not take into account the need to later change the XML file to fix XML errors. XML format errors, and better design choices, have been discovered by the community since the first RFCs were published using the XML format. In order to allow the RFC Editor to publish corrected XML for all RFCs, Section 5 of [RFC7990] is updated to say:¶
The XML file produced by the RFC Editor is the canonical format for RFCs; it is the format that holds all the information intended for an RFC. The RFC Editor may change the file over time to incorporate changes in the definition of the XML format.¶
The RFC Editor must keep archived sets of all renderings of the XML file for an RFC and the derived publication formats (HTML, PDF, and plain text) that were published. These archived sets must be available using the same access methods as for the XML and the published publication formats.¶
The XML file can be updated for the following limited reasons:¶
During the development of this document, many other reasons for updating the XML file were suggested. Those reasons are not in scope for this document, and may be adopted later after the community has experience with the updating mechanisms described in this document.¶
Section 7 of [RFC7990] describes the HTML, PDF, and plain text versions of an RFC that are published by the RFC Editor. The section is titled "Publication Format Documents", so that term is used here to refer to the documents that are derived from the XML for an RFC. When the XML changes, the RFC Editor may also regenerate the publication format documents and publish those new versions.¶
Whenever the RFC Editor publishes regenerated publication format documents, it must keep archived sets of all versions of the publication format documents files. These archived sets must be available using the same access methods as for the XML and the published publication formats.¶
[[ There was disagreement about the paragraph above about "must" and deciding when the publication format files are archived. ]]¶
(Separately, the RFC Editor might also regenerate one or more of the publication format documents for an RFC if it sees errors in the generated output. This has already happened in cases where PDF files had display errors in them. Such regeneration is an operational decision that is not affected by this document.)¶
When the RFC Editor archives documents, it does so in a manner that allows them to be found by people who want the historical (as compared to current) versions of those files.¶
To make the files easier to find, they should be stored in the same Internet-accessible locations as the current RFCs. The methods for storage and access will be determined by the RFC Editor in consultation with the technical community.¶
The naming of the archival files is a topic perfect for bike-shedding by IETF participants. Before this document is finished, hundreds (or thousands!) of messages, many with firm opinions of the best naming method, might be published. Heck, even the name of the directory for archival files is fodder for vigorous bike-shedding.¶
The file names for archived documents will be appended with a datestamp indicating the last day that the file was published as the XML or publication format documents. For example, if the XML for RFC 8888 is updated on March 4, 2024, the RFC Editor will publish the updated files as rfc8888.xml, rfc8888.html, rfc8888.pdf, and rfc8888.txt in the normal locations. It will also publish the files rfc8888-2024-03-04.xml, rfc8888-2024-03-04.html, rfc8888-2024-03-04.pdf, and rfc8888-2024-03-04.txt.¶
The same naming scheme is used when just a publication format document is published. For example, if the PDF of RFC 9432 had rendering issues that the RFC Editor fixes on January 8, 2024, the RFC Editor will publish tne updated file as rfc9432.pdf. It will also publish the file rfc9432-2023-01-08.pdf.¶
During the development of this document, members of the community said that the archived XML should contain an explanation for why the document was updated. Some suggested methods include:¶
Because each of these has one or more downsides, choosing between them is not bike-shedding.¶
[[ Martin T. expressed a preference for XML comments. ]]¶
This document has no IANA considerations.¶
This document has the same security considerations as [RFC7990]. Those are:¶
Changing the format for RFCs involves modifying a great number of components to publication. Understanding those changes and the implications for the entire tool chain is critical so as to avoid unintended bugs that would allow unintended changes to text. Unintended changes to text could in turn corrupt a standard, practice, or critical piece of information about a protocol.¶
This document has greatly benefitted from the input or the RSWG. In particular, Brian Carpenter, Jay Daley, and Martin Thomson gave significant input on the early draft of this document.¶