docs: ADR numbering discipline — assign numbers at merge-to-main
Codifies the fix for the ADR-0042 cross-branch collision (resolved this merge by renumbering the website ADR to 0044): ADR numbers are assigned when a branch merges to main, not at creation. On a branch, draft under a placeholder (ADR-XXXX title / draft-<slug>.md filename); main's docs/adr/README.md is the single source of truth for the next free number. - ADR-0000: new "Numbering discipline" section. - CLAUDE.md: pointer to it from the documentation-discipline note.
This commit is contained in:
@@ -38,6 +38,26 @@ The index lists ADRs in numerical order. Each entry shows the
|
||||
number, title, and — where relevant — status annotations such as
|
||||
"Superseded by ADR-NNNN" or "Deprecated".
|
||||
|
||||
## Numbering discipline
|
||||
|
||||
ADR numbers are a single global sequence, so two branches can each grab
|
||||
"the next number" independently and collide on merge. (This happened when
|
||||
the `website` branch's ADR-0042 met `main`'s ADR-0042, resolved by
|
||||
renumbering the former to ADR-0044.) To prevent it:
|
||||
|
||||
**Assign an ADR's number at merge-to-`main`, not at creation.** While the
|
||||
work lives on a non-`main` branch, draft the ADR under a placeholder — an
|
||||
`ADR-XXXX` title and a `draft-<slug>.md` filename — and reference it that
|
||||
way from any plan or notes. Give it the next free number only when the
|
||||
branch merges to `main`, renaming the file and updating its references in
|
||||
the same step.
|
||||
|
||||
A number is "taken" only once it appears in `main`'s `docs/adr/README.md`,
|
||||
which is the single source of truth for the next free number — never
|
||||
compute "next" from a feature branch. A branch that genuinely needs a real
|
||||
number up front may instead reserve one by landing a stub index entry on
|
||||
`main` first, but placeholder-until-merge is the default.
|
||||
|
||||
## Out-of-scope discipline
|
||||
|
||||
ADRs (and the plans they spawn) lean heavily on "out of scope" language.
|
||||
|
||||
Reference in New Issue
Block a user