docs(branching): fix the promotion ancestry precondition - #574
Merged
Conversation
The promotion procedure required `git merge-base --is-ancestor origin/main origin/next`. That check cannot pass after a successful promotion: promotion creates a merge commit on `main` that never exists on `next`, so `main` stops being an ancestor of `next` as soon as a promotion lands. ADR-0019 states the opposite property, that promotion needs no back-merge because the promoted `next` commit becomes an ancestor of `main`. Reading the failure as drift produced a no-content reconciliation merge before each promotion, the routine back-merge ADR-0019 set out to remove. Replace the precondition with an empty three-dot content diff, which holds right after a promotion and while work continues on `next`, and still fails when a genuine stable-only commit such as an unmerged hotfix exists on `main`. Note that the hotfix-synchronization step keeps the ancestor test, where it is correct, because that direction merges `main` into `next`.
This was referenced Aug 30, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Fixes the promotion precondition in
runbooks/branch-protection.md, whichrequired a check that cannot pass after any successful promotion.
Closes #573
Problem
Step 1 of the promotion procedure required:
Promotion creates a merge commit on
mainthat never exists onnext, somainstops being an ancestor ofnextthe moment a promotion lands. ADR-0019states the opposite property, that promotion needs no back-merge because the
promoted
nextcommit becomes an ancestor ofmain. Both cannot hold.Reading the guaranteed failure as drift has produced three no-content
reconciliation merges in
z-shell/zi(9a4fa51,b0ebcc3,73df7bf), eachcontributing zero files to
next. That is the routine back-merge ADR-0019 setout to remove.
Change
Replaces the precondition with an empty three-dot content diff, which asserts
what the step was actually trying to establish: the stable branch carries no
content the candidate lacks.
Also documents why the ancestor test is correct in the hotfix-synchronization
step, where the merge runs in the opposite direction. That asymmetry is the
likely origin of the defect.
Verification
Both checks exercised across the four states a persistent integration branch can
occupy, in a scratch repository:
next, healthymainThe third row confirms this is not a check that passes unconditionally: a
genuine stable-only commit is still caught.
Applied to the live pending
z-shell/zicandidate, the new check passes wherethe old one falsely failed, and
git diff --name-only origin/next...origin/mainis empty.
trunk checkreports no issues on the changed file.Follow-up
z-shell/zicarries the same defect in.github/PULL_REQUEST_TEMPLATE/promotion.md, which would reimpose theimpossible check on the promotion pull request itself. Tracked separately and
should land before the pending promotion.