Lifecycle · History

RFCs and ADRs have a status. Spec pages and refs do not.

Statuses

draft, proposed, accepted, rejected and withdrawn. The last three are terminal. A document with a terminal status is frozen: any change to it once it exists on the configured branch is reported by lint, and every writer refuses it.

Transitions

In strict mode, the default:

From	To
`draft`	`proposed`, `withdrawn`
`proposed`	`accepted`, `rejected`, `withdrawn`
`accepted`	none
`rejected`	none
`withdrawn`	none

Non-strict mode adds draft → accepted and draft → rejected. No other transition exists in either mode. proposed → draft is never permitted.

Transition commands

archdoc propose <id>, accept <id>, reject <id> and withdraw <id> each:

Load the document. Fail if the identifier is unknown or the type is not RFC or ADR.
Check the transition is permitted from the current status under the strict setting. Fail naming the transitions permitted from the current status.
For accept ~~and reject~~: fail if ~~there is no H1, or it does not read as~~ the front matter gives it; fail if a required section is missing, or appears before one it must follow; fail if any required section is empty; fail if any unresolved [[...]] remains. For accept: fail if the document has ~~a closing section and another H2 follows it; fail if the document has~~ an Open questions section and it is non-empty, naming Resolved questions. ~~For both, then: fail at the first fault L20 or L21 reports, naming its line, with each Changelog entry's date compared against today, the~~ decided date about to be written, rather than the document's own. withdraw performs no content checks.
Rewrite status and, for a terminal transition, decided to today. Front matter is rewritten field by field, preserving order and comments. The body is not touched except in step 5.
For reject: append ## Rejection rationale to the end of the body with an HTML comment prompting for the rationale.

For accept and reject: fail if lint reports any error other than L03 about the document as rewritten, judged within the rest of the repository and, for reject, with the rejection rationale taken as written, listing each error as lint prints it. ~~The step 3 checks run~~ L11 compares the file on disk with the configured branch, so it judges the document as it stood before the transition. The file is written only once this ~~append~~passes.
Print the new status.

A transition refuses to write a decided date earlier than created, and refuses a status the graph does not know. reject refuses a document whose parse stops short of the end of the file. None of the transition commands commits.

Backfilling

archdoc new --backfill creates a document already in a terminal status, with created and decided set to the dates given and backfilled set to today. A backfilled document uses no transition. It requires a Sources section, and Alternatives considered and Backwards compatibility are pre-filled with Not recorded..