An accepted RFC isn't edited: a later RFC changes it, with Updates: or Obsoletes: under its title as IETF RFCs do, and the old one gets an Updated by: or Obsoleted by: back-link. Fixes that don't change the meaning are ordinary PRs. An RFC can name a living document for the current rules. Updates RFC-0000, which gets its back-link here. Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
3.2 KiB
RFC-0013: Amending an accepted RFC
Updates: RFC-0000
Summary
An accepted RFC is not edited. A later RFC changes it and says so under its
title, with Updates: or Obsoletes:, as IETF RFCs
do. The only change an accepted RFC gets is a line under its title pointing to
the RFC that updates or obsoletes it, and fixes that don't change its meaning.
An RFC can name a separate document that holds the current rules, so nobody has
to read an RFC and all its amendments to find them.
Motivation
RFC-0000 says decisions are made through RFCs that
add rfcs/NNNN-short-title.md, but not what happens when an accepted RFC needs
to change. Editing it in place keeps the file current but loses the record: the
comment period and the approval were given to the old text, and only the git
history shows what was decided when. Rules that apps adopt one by one, such as
shared conventions, will change as they meet real code, so this will come up
soon.
Proposal
-
An accepted RFC's text doesn't change, except as in points 3 and 4.
-
A change is a new RFC that says under its title which RFC it changes:
Updates: RFC-NNNNchanges part of it; the rest still stands.Obsoletes: RFC-NNNNreplaces it entirely.
It follows RFC-0000's process, with the comment period the changed RFC needed: 7 days if that one is about adding or removing an app or about this process, 3 days otherwise.
-
The same PR adds a back-link under the old RFC's title:
Updated by: RFC-MMMMorObsoleted by: RFC-MMMM. Someone reading the old RFC must be able to see that it is no longer the whole story. -
Fixes that don't change the meaning, such as typos, broken links and formatting, go in ordinary PRs, with a maintainer's approval and no comment period. A fix that changes the meaning needs an
Updates:RFC. -
An RFC can name a living document, such as
docs/<topic>.md, that holds the current rules it sets. Wording fixes there are ordinary PRs, as in point 4. Adding, removing or changing a rule needs an RFC that updates the one naming the document, and that RFC's PR changes the document too.
This RFC updates RFC-0000, so its PR adds Updated by: RFC-0013 to RFC-0000.
Alternatives
- Edit accepted RFCs in place. The file is always current, but a reader can't tell which parts were reviewed and accepted, and which were changed later with less scrutiny, without reading the git history.
- Version numbers inside each RFC (v1, v2, …). The same problem: one file holds several decisions, and the reader has to work out which one is in effect.
- Keep the back-links in an index instead of the RFC, as the IETF does in its RFC index. That works when everyone reads the index first. Here people open the file from a link, so the pointer has to be in the file.
Open questions
- Should obsoleted RFCs move to a separate folder? This RFC proposes not, so links to them keep working.
- The IETF also keeps a list of reported errors (errata). Point 4 covers errors
that don't change the meaning, and an
Updates:RFC covers the rest. Is a separate list needed?