Updating RFCs
CA Technologies
dret@ca.com
http://dret.net/netdret/
As part of document metadata, RFCs can reference existing RFC that they update or obsolete. While obsoleting is well-understood (replace the obsoleted RFC in its entirety), updating has more nuances because the updated RFC remains valid. This document contains some clarifications about how to handle updating in a way that makes it easier for readers to understand how the original and the updating RFC relate.
This draft should be discussed on the wgchairs mailing list.
Online access to all versions and files is available on github.
The "RFC Style Guide" defines two possible ways in which an RFC can relate to existing RFCs: It can obsolete existing RFCs, and/or it can update existing RFCs. When obsoleting an RFC, the obsoleted RFC is effectively replaced in its entirety by the obsoleting RFC (or parts of it). For updates, the relationship is a little less clear.
The obsoleted "Instructions to RFC Authors" in Section 12 describe what "Updates" and "Obsoletes" mean. These descriptions do not appear in RFC 7322, and even if they did, they might still not always be sufficient to understand the exact nature of the update.
This memo therefore recommends that RFC authors should include explicit information about any updates that their RFC makes, and include this in a place where it is easy to locate. This way, readers of the updated RFC as well as those of the updating RFC can easily understand how the two documents relate.
This document clarifies the way in which RFCs should describe their relationship to updated RFCs. It proposes to include individual "Reasons for updating RFC ..." sections for all updated RFCs as section(s) early on in the document. These sections are supposed to supplement the more formal "Updates" metadata and are not intended to replace it.
RFC authors that use "Updates" in their document should include individual "Reasons for updating ..." sections for each updated RFC. These sections should be placed relatively early in the document. In each of these sections, there should be a short description of the nature of the update.
Authors should note that these sections are in no way intended to replace the more formal "Updates" metadata in the RFC itself. Instead, for each of the RFCs listed in the "Updates" metadata, one such section should be added.
When writing these sections, it helps to specifically think about the two possible perspectives:
When reading the updating RFC, there is a clear dependency on the updated RFC. The most important question for somebody reading and implementing the updating RFC is how this will affect interoperability with implementations only implementing the updated RFC. Documenting the expected behavior will make it easier for implementers to understand the how different implementations can be expected to interact.
When reading the updated RFC, it is important to keep in mind that it is still valid as a standalone document. The most important question for somebody who has implemented the updated RFC is how the new updating RFC may affect interoperability. Documenting why the updating RFC chose to explicitly update (instead of just being an extension/add-on) will make it easier to understand the nature of the update.
Generally speaking, using "Updates" often has one of two possible motivations: One is a bug fix or a clarification that negatively affected the original specification, in at least some of the scenarios and implementations. In such a case, the update should be of interest to everybody implementing the updated RFC, and the section clearly state why and how that is the case.
The second motivation is that the updating RFC is a backwards compatible extension, which means that strictly speaking, it does not even need to mention the updated RFC. However, there may be reasons to establish the relationship between the RFCs so the implementers are aware of it and that new implementations of the updated RFC are more likely to also implement the extension in the updating RFC. In such a case, the section should be clear about the fact that the update is optional, and may make a case for new implementations to support the extension as well.
In case of non-protocol documents (such as this one), the general question is the same: Does the updated practice specified in the updating document warrant mentioning in the updated RFC? Once again, if the author of the updating RFC thinks that this would be appropriate, the explanation of the practice update should be given in the "Reasons for updating ..." Section , so that it is easy to understand why and how the practice was updated.
RFC Style Guide
This document describes the fundamental and unique style conventions and editorial policies currently in use for the RFC Series. It captures the RFC Editor's basic requirements and offers guidance regarding the style and structure of an RFC. Additional guidance is captured on a website that reflects the experimental nature of that guidance and prepares it for future inclusion in the RFC Style Guide. This document obsoletes RFC 2223, "Instructions to RFC Authors".
Instructions to RFC Authors
This Request for Comments (RFC) provides information about the preparation of RFCs, and certain policies relating to the publication of RFCs. This memo provides information for the Internet community. This memo does not specify an Internet standard of any kind.
Thanks for comments and suggestions provided by Benoit Claise and Tony Hansen.