chore(workflow): branch-and-PR working method + ADR-number reservation (ADR-0059)
Adopt a trackable working method now the repo is public: - PRs onto a protected main; --no-ff merge commits; one worktree per branch. - Reserve-first ADR numbering: scripts/adr-reserve.sh claims the next number atomically against main (push = compare-and-swap; ledger docs/adr/RESERVATIONS.log), so a number is stable from creation. - Worktree helpers scripts/wt-new.sh + wt-clean.sh. - Local-origin test harnesses (reserve 10/10, worktrees 7/7, shellcheck clean). Record the decision in ADR-0059, supersede ADR-0000's placeholder-until-merge numbering default, and add the lean CONTRIBUTING.md sections + CLAUDE.md operational rules.
This commit is contained in:
@@ -45,18 +45,23 @@ ADR numbers are a single global sequence, so two branches can each grab
|
||||
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.
|
||||
**Reserve the number up front, via `scripts/adr-reserve.sh`** (ADR-0059,
|
||||
which superseded the earlier placeholder-until-merge default). The moment
|
||||
you know an ADR is needed — at branch start or mid-branch — run
|
||||
`scripts/adr-reserve.sh <slug> "<title>"`. It atomically claims the next
|
||||
free number against `main` (the remote ref is the registry; a `git push`
|
||||
is the compare-and-swap, retried on contention) and records it in the
|
||||
append-only ledger `docs/adr/RESERVATIONS.log`. The number is then **stable
|
||||
from creation**, so it is safe to cite in commit messages (immutable under
|
||||
the no-rewrite rule), in other ADRs, and in the PR from the first commit.
|
||||
Create the ADR as `docs/adr/<NNNN>-<slug>.md` and add its README index row
|
||||
as part of the branch's normal work.
|
||||
|
||||
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.
|
||||
A number is "taken" once its ledger line (or `NNNN-*.md` file) is on
|
||||
`main`; the script reads both to compute the next free number — never
|
||||
compute "next" by hand from a feature branch. The full rationale (why
|
||||
reserve-first beats number-on-merge, issue-number ids, or an allocator bot)
|
||||
is in **ADR-0059**.
|
||||
|
||||
### Subproject ADR namespaces
|
||||
|
||||
|
||||
Reference in New Issue
Block a user