docs(minicloud): correct the merge runbook against what the merges did - #15750
Merged
Conversation
Collaborator
✅ Test Summary: PASSED✅ Precommit: PASSED
✅ Tests: PASSED
|
Three things the runbook got wrong or did not know, all found while executing it: A GitHub stack object is separate from the base refs and was the actual merge blocker. 15617's base was already master, yet the button stayed unavailable and retargeting 15618 was refused outright — stack #15619 had to be dissolved with 'gh stack unstack'. The runbook had assumed base refs were the whole story. jenkins/precommit does not necessarily clear when the base becomes master. On 15618 the stacked-PR baseHash artifact was masking a real ruff-format failure in two of its own files; both look the same from outside, so the changed files have to be checked directly. 'git checkout -B <pr-branch>' fails when that branch is checked out in another worktree, and the following rebase then runs on the wrong branch. Use a scratch name and push with an explicit HEAD:<branch> refspec.
dimakr
force-pushed
the
docs/minicloud-runbook-corrections
branch
from
August 12, 2026 20:33
7c7d46f to
4da46f1
Compare
dimakr
approved these changes
Aug 12, 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
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.
What
Corrects
docs/plans/minicloud-stack-merge-runbook.md, which landed with #15617 and turned out to be wrong in three places once it was actually executed. Docs only, one file.1. A GitHub stack object is separate from the base refs, and it is what blocks the merge
The runbook assumed base refs were the whole story, so it said GitHub would auto-retarget on merge and nothing else was needed. In reality these three PRs were bound into stack #15619 (size 3), and while it existed:
masterand every required check passed;Cannot change the base branch because the pull request is part of a stack.gh stack unstack 15619dissolved it and left every base ref untouched, so the dependents kept their clean 8- and 2-commit diffs. Now documented with how to read the stack number, thatgh stack linkis the inverse, and thatgh pr merge --rebase --admingets an admin past a missing approval (enforce_adminsis false onmaster).2.
jenkins/precommitdoes not necessarily clear when the base becomesmasterThe runbook claimed it "should flip from fail to pass" after the restack, treating the failure as purely a stacked-PR artifact. It did not flip — the artifact was masking a real failure, and both look identical from outside. #15618's console had them one after the other:
The first line is the stacking artifact (
baseHashderived from an unreachable merge ref). The second was genuine: two files in #15618's own commits failedruff format --checkwhile passing at master. Now says to check the changed files directly, with the commands, and to fix via--fixup+--autosquashrather than leaving fixup commits.3.
git checkout -B <pr-branch>can silently rebase the wrong branchgit checkout -B feature/minicloud-pipelines pr/15618fails with "already used by worktree at ..." when that branch is checked out elsewhere — and because the followinggit rebaseis a separate command, it then runs on whatever branch you were already on. Mine produced 10 commits instead of 8 before I caught it. The runbook now uses a scratch branch name and pushes with an explicitHEAD:<branch>refspec.Also refreshed: Step 1 and 2 marked done with the SHAs the merge actually produced, the stale
OLD_BASE=139b5499dbreplaced (15617's head moved when the runbook commit was added to it — the point of reading it rather than remembering it),--force-with-leasepins switched togit ls-remote, and a note that #15668 must be restacked after any force-push to #15618, not only after its merge.Tests
Docs only — no code paths touched.
pre-commitclean on the changed file.🤖 Generated with Claude Code