chore(workflow): branch-and-PR working method + ADR-number reservation (ADR-0059) #41

2026-06-23T21:45:46+01:00

claude-clouddev1 commented

2026-06-23 21:45:46 +01:00

Adopts a trackable working method now the repo is public. Decision recorded in ADR-0059; the public-facing subset is in CONTRIBUTING.md.

What

PRs onto a protected main (always-green; no direct pushes bar one carve-out), one logical change per branch, conventional prefixes, the /runda/DA review pasted into each PR.
One worktree per branch (<repo>-worktree-<segment>, the existing convention) via scripts/wt-new.sh / scripts/wt-clean.sh — never switch the primary checkout (that's how work gets clobbered).
Merge commits (--no-ff), never rebase/squash — the only strategy consistent with append-only history.
Reserve-first ADR numbering (scripts/adr-reserve.sh): the fix for the real collision problem. A contiguous integer needs an allocator and plain git branches have none — so main is the registry and an atomic git push is the lock (compare-and-swap, retried on contention), recorded in the append-only ledger docs/adr/RESERVATIONS.log. The number is stable from creation, so it's safe in immutable commit messages and cross-refs from commit #1 — which number-on-merge is not. Supersedes ADR-0000's placeholder-until-merge default; subproject namespaces (ADR-website/ci-NNN) unchanged.

Branch protection (already applied)

Require PR + the ci / gate* status check + up-to-date-before-merge; owner whitelisted for direct push — the sole sanctioned direct commit, the reservation ledger line.

Tests

Local-origin harnesses, no network/keys needed:

scripts/test-adr-reserve.sh — 10/10: number computation, dry-run, real push, sequential allocation, idempotence, hard-rejection-aborts-not-loops, and the race-vs-abort discriminator.
scripts/test-wt.sh — 7/7: branch+worktree creation, bad-prefix/duplicate guards, merged-vs-unmerged cleanup.
All scripts shellcheck-clean. The reserve script's real-remote push path was dogfooded live, reserving ADR-0058 and ADR-0059.

Forks (user-chosen)

merge-commit (vs squash/ff-only); strict everything-via-PR; protection enforced in Gitea; reserve-first integers (vs number-on-merge / issue-number ids / an allocator bot); worktrees prescribed.

Suggested merge order: this PR first (lands the working method + tooling on main), then the #37 PR. Whichever merges second hits a one-line README.md index conflict (0058 vs 0059 row) — resolve by keeping both in numeric order.

Adopts a trackable working method now the repo is public. Decision recorded in **ADR-0059**; the public-facing subset is in `CONTRIBUTING.md`. ## What - **PRs onto a protected `main`** (always-green; no direct pushes bar one carve-out), one logical change per branch, conventional prefixes, the `/runda`/DA review pasted into each PR. - **One worktree per branch** (`<repo>-worktree-<segment>`, the existing convention) via `scripts/wt-new.sh` / `scripts/wt-clean.sh` — never switch the primary checkout (that's how work gets clobbered). - **Merge commits (`--no-ff`)**, never rebase/squash — the only strategy consistent with append-only history. - **Reserve-first ADR numbering** (`scripts/adr-reserve.sh`): the fix for the real collision problem. A contiguous integer needs an allocator and plain git branches have none — so **`main` is the registry and an atomic `git push` is the lock** (compare-and-swap, retried on contention), recorded in the append-only ledger `docs/adr/RESERVATIONS.log`. The number is **stable from creation**, so it's safe in immutable commit messages and cross-refs from commit #1 — which `number-on-merge` is not. Supersedes ADR-0000's placeholder-until-merge default; subproject namespaces (`ADR-website/ci-NNN`) unchanged. ## Branch protection (already applied) Require PR + the `ci / gate*` status check + up-to-date-before-merge; **owner whitelisted for direct push** — the sole sanctioned direct commit, the reservation ledger line. ## Tests Local-`origin` harnesses, no network/keys needed: - `scripts/test-adr-reserve.sh` — **10/10**: number computation, dry-run, real push, sequential allocation, idempotence, hard-rejection-aborts-not-loops, and the race-vs-abort discriminator. - `scripts/test-wt.sh` — **7/7**: branch+worktree creation, bad-prefix/duplicate guards, merged-vs-unmerged cleanup. - All scripts `shellcheck`-clean. The reserve script's real-remote push path was dogfooded live, reserving **ADR-0058** and **ADR-0059**. ## Forks (user-chosen) merge-commit (vs squash/ff-only); strict everything-via-PR; protection enforced in Gitea; reserve-first integers (vs number-on-merge / issue-number ids / an allocator bot); worktrees prescribed. --- > Suggested merge order: **this PR first** (lands the working method + tooling on `main`), then the #37 PR. Whichever merges **second** hits a one-line `README.md` index conflict (`0058` vs `0059` row) — resolve by keeping both in numeric order.

claude-clouddev1 added 1 commit 2026-06-23 21:45:47 +01:00

chore(workflow): branch-and-PR working method + ADR-number reservation (ADR-0059)

ci / gate (push) Successful in 2m5s

Details

ci / manifests (push) Successful in 4s

Details

ci / gate (pull_request) Successful in 2m5s

Details

ci / manifests (pull_request) Successful in 4s

Details

b5c848efcb

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.

oli added 1 commit 2026-06-23 22:01:21 +01:00

Merge branch 'main' into chore/dev-workflow

ci / gate (pull_request) Successful in 2m2s

Details

ci / manifests (pull_request) Successful in 4s

Details

63d11402ae

oli merged commit 3585cca5ea into main

2026-06-23 22:08:28 +01:00

oli deleted branch chore/dev-workflow

2026-06-23 22:08:29 +01:00

claude-clouddev1 referenced this pull request