From 9e774b2dfa428214e409a850fbae01c73f8f6ae3 Mon Sep 17 00:00:00 2001 From: "claude@clouddev1" Date: Tue, 9 Jun 2026 20:30:36 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20ADR=20numbering=20discipline=20?= =?UTF-8?q?=E2=80=94=20assign=20numbers=20at=20merge-to-main?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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-.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. --- CLAUDE.md | 5 ++++- .../adr/0000-record-architecture-decisions.md | 20 +++++++++++++++++++ 2 files changed, 24 insertions(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index bfd358d..f3f9e70 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -165,7 +165,10 @@ Key invariants in the code: ADR. In-flight discussion stays in conversation or issues until it settles. The ADR-0000 index-upkeep rule applies: every ADR change updates `docs/adr/README.md` in the same - edit. + edit. ADR **numbers** are assigned at merge-to-`main` (draft + under a placeholder `ADR-XXXX` / `draft-.md` on a + branch) to avoid cross-branch collisions — see ADR-0000 + "Numbering discipline". - **Issue tracking.** Bugs and enhancements are filed as Gitea issues (see *Issue tracking — Gitea via `tea`* below). `docs/requirements.md` and the ADRs remain the source of truth diff --git a/docs/adr/0000-record-architecture-decisions.md b/docs/adr/0000-record-architecture-decisions.md index deefd4e..a12b3b1 100644 --- a/docs/adr/0000-record-architecture-decisions.md +++ b/docs/adr/0000-record-architecture-decisions.md @@ -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-.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.