RFC process
On this page
An RFC records one technical decision: what is proposed, why, and what was rejected. This page defines when an RFC is needed and how it moves from draft to accepted.
What an RFC contains
RFCs are thin. An RFC holds the decision and its reasoning. It does not hold the normative text. The exact rules, formats and behavior are written in the state documents the RFC changes: architecture pages, specifications, handbook pages. Those changes belong to the same change set as the RFC.
A reader who wants to know what cotty does reads the state documents. A reader who wants to know why reads the RFC.
The skeleton is in Templates.
When an RFC is required
Write an RFC when a decision:
- is hard to reverse;
- crosses a boundary that others depend on: a wire protocol, an on-disk format, a public API, the security model;
- shapes several parts of the system at once;
- changes how the project works.
No RFC is needed to fix an error, to clarify wording without changing meaning, or to change details inside one component that do not change its documented behavior.
Product changes are not made by RFC. They go through a version design. An RFC names the product scenario it serves.
Lifecycle
| Status | Meaning |
|---|---|
draft |
Being written. Not ready for a decision. |
discussion |
Complete, and waiting for a decision. |
accepted |
Decided. The state documents it affects are updated. |
implemented |
The code matches it. |
rejected |
Decided against. Kept as a record. |
withdrawn |
Dropped by its author. |
superseded |
Replaced by a later RFC, named in superseded_by. |
stateDiagram-v2
[*] --> draft
draft --> discussion
discussion --> draft
discussion --> accepted
discussion --> rejected
draft --> withdrawn
discussion --> withdrawn
accepted --> implemented
accepted --> superseded
implemented --> supersededThe project maintainer decides acceptance.
A change set
A change set for an RFC contains:
- The RFC, in both languages, under the next free number.
- The changes to the state documents. The RFC lists those pages in
affects. Each of those pages lists the RFC number inrfcs.
While the RFC is in draft or discussion, a state page that the RFC introduces has the status draft.
Acceptance
An RFC can be accepted when:
- each open question is resolved, or is deferred with a stated reason;
affectslists at least one page, and those pages contain the change;- the checks pass.
On acceptance, the status becomes accepted in both languages, and the pages the RFC introduced become accepted.
After acceptance
An accepted RFC is not rewritten. Only its status, its superseded_by field and plain errors change. To change a decision, write a new RFC that names the old one in supersedes.
Where a state document and an RFC disagree, the state document governs.
Numbers
An RFC file is named NNNN-slug.md, with four digits. A number is never reused, including the numbers of rejected and withdrawn RFCs.