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.

M03, run by archdoc lint --merge, judges a pull request's changes of status by the same table, from the status on the configured branch and under that branch's strict. See lint Lint.

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: fail if the document has an Open questions section and it is non-empty, naming Resolved questions. 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. 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 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..