From ea613e33ca2ed578b85d1da2cf0b53e1140433cc Mon Sep 17 00:00:00 2001 From: Emi Griffith Date: Sat, 1 Aug 2026 17:14:45 -0700 Subject: [PATCH] flow: squash into dev, fast-forward the promotions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Forgejo cannot scope merge styles per branch — they live on the repo's pull-request unit, and BranchProtection carries no merge-style or linear-history field in 9.0.3. So the chain is enforced repo-wide by allowing exactly two styles: squash and fast-forward-only. Merge commits and rebase merges are off. Squash belongs on the short-lived hop. Squashing dev into main would put a commit on main that does not have dev's commits as ancestors, freezing merge-base(dev, main); every later promotion would then list all commits since that stale point and re-apply changes main already has. Fast-forwarding the promotions instead means a promotion creates no commit at all, so the three branches keep identical history rather than merely identical trees, and `release ⊆ main ⊆ dev` holds permanently. Rebase-updates stay enabled. They are a different setting from rebase merges, and BRANCHING.md is right that the merge queue 403s without them. Also adds `release` to pr-build.yml's pull_request branches. This is step one of the order BRANCHING.md prescribes for closing the missing check on release: teach the workflow to fire there, confirm on a real PR that the context appears, and only then require it. Requiring a context nothing produces is what makes a production promotion unmergeable with a 405 that names no cause. --- .claude/BRANCHING.md | 10 ++++++++-- .forgejo/workflows/pr-build.yml | 2 +- CLAUDE.md | 15 +++++++++++++++ 3 files changed, 24 insertions(+), 3 deletions(-) diff --git a/.claude/BRANCHING.md b/.claude/BRANCHING.md index e602fbc..bef5ba2 100644 --- a/.claude/BRANCHING.md +++ b/.claude/BRANCHING.md @@ -71,8 +71,14 @@ correct" rather than erroring. is a divergence to reconcile deliberately, not to overwrite. 2. **`dev` is the default branch.** `forge_repo_settings(apply_flow_defaults=true)` — sets the default branch and - permits every merge style the chain uses, including `fast-forward-only`, plus - rebase-updates (without which the merge queue's core primitive 403s). + permits the merge styles the chain uses, plus rebase-updates (without which + the merge queue's core primitive 403s). + + The chain uses exactly two: **squash** for `feat/*` → `dev`, and + **fast-forward-only** for both promotions. Merge commits and rebase merges + are disabled deliberately — see the merge-style table in the root + `CLAUDE.md`. If `apply_flow_defaults` re-enables them, that is the tool + disagreeing with the policy, not permission to use them. 3. **Protection.** `forge_branch_protection(branch="dev", apply=true)`, then `main`, then `release`. diff --git a/.forgejo/workflows/pr-build.yml b/.forgejo/workflows/pr-build.yml index 578aa9d..8ac368d 100644 --- a/.forgejo/workflows/pr-build.yml +++ b/.forgejo/workflows/pr-build.yml @@ -19,7 +19,7 @@ name: PR build (required check) on: pull_request: - branches: [dev, main] + branches: [dev, main, release] concurrency: group: pr-build-${{ github.event.pull_request.number }} diff --git a/CLAUDE.md b/CLAUDE.md index f81e631..afa51e8 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -22,6 +22,21 @@ every change, so a stale one is a correctness bug, not a documentation bug. `dev`, `main` and `release` are protected: **everything is a PR**, for humans and agents alike. Promotion is one PR per hop, `dev` → `main` → `release`. +**Merge style is part of the contract**, and Forgejo enforces it repo-wide — +it cannot scope styles per branch, so these are the only two enabled: + +| Hop | Style | +|---|---| +| `feat/*` → `dev` | **squash** | +| `dev` → `main`, `main` → `release` | **fast-forward only** | + +Merge commits and rebase merges are disabled. A promotion therefore never +creates a commit, which keeps `release ⊆ main ⊆ dev` true permanently: the +three branches hold identical history, never merely identical trees. Squashing +into `main` instead would strand `merge-base(dev, main)` and make every later +promotion re-apply work already there. Rebase-*updates* stay enabled — the +merge queue 403s without them. + `.claude/BRANCHING.md` is the orchestrator's runbook for that flow — the serialised merge queue, promotions, hotfix down-merges — and `.claude/ownership.md` is the module map saying which tasks may run