Skip to content
codemode-executor

Decision records

Decision records exist so a settled question does not get argued from scratch by whoever forgot it was settled. Each one captures a single choice that shapes the repository for its lifetime, the situation that forced it, and what the repository pays for it. No diff carries any of that, so these are written separately and kept.

When to write one

Section titled “When to write one”
  • Write a record for a decision that constrains future choices: the runtime, the containment model, the compatibility strategy, the way a class of problem gets solved from now on.
  • Do not write a record for a code-style rule. Naming, comment discipline, test layout and formatting live in the topic files next to this directory, stated as rules and not as history, because nobody needs to know when a formatting convention was adopted.
  • Write the record when the decision is made, not after the code lands. A record written from a finished diff argues for the diff and never describes the choice, and the alternatives it lists will be the ones that lost.

One question settles most cases. If the decision could plausibly be revisited in a year, and revisiting it would require knowing what was already weighed and rejected, it is a record.

Numbering

Section titled “Numbering”

Records are numbered in the order they are written, four digits, starting at 0001. Each new record takes the next free number. Its Date line carries the day the decision was taken, so the numbers do not run in date order. The file name is the number, a hyphen, and a short slug of the title: 0003-sandbox-targets-workerd-surface.md. 0000-template.md is the template, not a decision. Numbers are never reused and never reordered. A gap in the sequence means a record was withdrawn before acceptance.

Records are never edited

Section titled “Records are never edited”

Every record states what was decided on the day it was decided. Once accepted, its Context, Decision and Consequences are frozen. Correct one in place and you destroy the only artifact explaining why the repository once did something else. That artifact is precisely what somebody needs on the day they propose doing it again.

Every decision that changes gets a new record. The new record cites the old one, and the old record’s status becomes superseded by NNNN. That status line is the one edit an accepted record ever receives.

Reopening a settled question

Section titled “Reopening a settled question”

Read the existing records first. Several of the choices here were reached by weighing the obvious alternative and rejecting it for a stated reason, and the reason is usually still true. Proposals that reopen a decided question are welcome when they bring evidence the record does not already answer. But one that only restates the rejected alternative spends everyone’s review on an argument that already happened.

Records, in number order

Section titled “Records, in number order”