On this page
  1. What an RFC contains
  2. When an RFC is required
  3. Lifecycle
  4. A change set
  5. Acceptance
  6. After acceptance
  7. Numbers

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 --> superseded

The project maintainer decides acceptance.

A change set

A change set for an RFC contains:

  1. The RFC, in both languages, under the next free number.
  2. The changes to the state documents. The RFC lists those pages in affects. Each of those pages lists the RFC number in rfcs.

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;
  • affects lists 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.