The pull-request workflow, from draft to drained stack

A pull request asks a reviewer to understand a change well enough to share responsibility for it. Everything about a good PR makes that cheaper.

One purpose per PR

GitHub's own advice: "Small, focused pull requests are easier to review and safer to merge." The test is whether you can state the purpose in one sentence. "Bump the ORM, refactor the repository layer, and add order export" is three PRs:

PR 1  Bump the ORM to 7.2                     (mechanical; reviewer skims)
PR 2  Move order queries into OrderRepository (refactor; no behaviour change)
PR 3  Add CSV export for orders               (the feature; the real review)

Each is easy to say yes to, easy to revert alone, and fails CI for one reason. If PR 3 needs PR 2, that's a stack — the complex example covers merging one.

Before asking anyone else, review it yourself: read the whole diff in the Files changed tab, look for debug output, stray files and unrelated formatting, and check that CI is green.

Commit messages that survive

Git's own manual: "begin the commit message with a single short (no more than 50 characters) line summarizing the change, followed by a blank line and then a more thorough description." Pro Git adds: write it in the imperative — "Fix bug", not "Fixed bug" — and use the body for the motivation.

Round cart totals once, after summing

Line totals were rounded individually and then summed, so a cart of
three $0.333 items showed $0.99 instead of $1.00. Sum the exact
amounts and round the result.

The subject is what git log --oneline, git revert and every review tool show. The body is for the person running git blame on this line in two years: why, not a list of files.

A description that does the reviewer's first five minutes

• Why — the problem, or a link to the issue.
• What — the approach, in a few lines.
• Where to look — "the logic is in pricing.ts; the rest is fixture updates".
• How it was checked — tests added, what you ran by hand.

Fixes #88 (or Closes, Resolves) in the description links the issue and closes it when the PR merges — but only when the PR targets the repository's default branch. Against any other base, GitHub's docs say the keywords are ignored.

A green "Merge" button means the repository's rules are satisfied — not that the change is right. Those rules live in branch protection (or the newer rulesets) on the target branch. The settings you'll meet most, as GitHub's docs describe them:

By default a protection rule also blocks force-pushes and deletion of that branch — which is why git push --force to a protected main fails no matter what you type. And by default the rules don't apply to repository admins unless "Do not allow bypassing the above settings" is on.

Status checks: the CI gate

A status check is a pass/fail/pending result attached to a commit, usually posted by CI. Only checks marked required gate the merge; the rest are information.

% gh pr checks 42 --required --watch      # wait for the required checks on PR #42

Strict vs loose. With "require branches to be up to date", a PR that was green yesterday must take in the latest main (Update branch, or rebase and push) and pass again before it can merge. That catches two PRs that each pass alone and break together, at the cost of more CI runs. A merge queue gives the same guarantee without making every author update by hand.

Auto-merge: say yes now, merge when it's ready

gh pr merge 42 --squash --auto

When reviews or checks are still pending, --auto enables auto-merge: GitHub merges as soon as every requirement is met. GitHub switches it off again if someone without write access pushes to the branch or changes its base branch.

Why this matters to you as an author

• A PR that's "approved" but red can't merge; a PR that's green but unreviewed can't either. Read the merge box — it lists exactly which requirement is missing.
• A required check is only as good as the job behind it. The complex example shows two ways a required check reports "passing" or "blocked" for reasons unrelated to your code.

A hand-built stack: PR #1 merges feature-a into main; PR #2 merges feature-b into feature-a, so it shows only b's diff. Reviews happen in parallel. Merging is where stacks go wrong, and there are two separate failure modes.

Failure 1: the base branch disappears and takes PR #2 with it

GitHub's docs describe the happy path: "If you delete a head branch after its pull request has been merged, GitHub checks for any open pull requests in the same repository that specify the deleted branch as their base branch" and changes their base to the merged PR's base. The docs don't say whether every way of deleting the branch triggers that.

Not every way does. gh pr merge 1 --delete-branch deletes the remote branch through the API, and the GitHub CLI issue tracker has an open bug from 2020 (cli/cli#1168) in which the child PR is closed instead of retargeted; a commenter there traced it to the API call that deletes the branch. A similar report from August 2026 (cli/cli#14223) is labelled a platform bug and still open. One commenter on #1168 found that turning on the repo's "Automatically delete head branches" setting avoided it in 2020 and no longer did by 2024. Once closed, the PR can't be retargeted (Cannot change the base branch of a closed pull request.), and in #14223 reopening it was refused too — so PR #2 may have to be recreated, losing its review history.

Don't depend on which deletion path you took. Retarget first, then merge and delete:

gh pr edit 2 --base main          # PR #2 now targets main (its diff briefly includes a's commits)
gh pr merge 1 --squash            # merge the bottom PR; if gh offers to delete the branch, say no

Failure 2: after a squash, the upper branch still carries the old commits

main now has one squash commit; feature-b still has A1, A2 underneath B1. Rebase only b's own commits onto main — your local feature-a branch marks where they start, which is why it's worth keeping until this step is done:

git fetch
git switch feature-b
git rebase --onto origin/main feature-a     # replay feature-a..feature-b
git push --force-with-lease                 # PR #2 now shows only b's diff again
git push origin --delete feature-a          # safe now: nothing targets it

With a merge commit instead of a squash, a plain git rebase origin/main does the same job, because A1, A2 are already in main's history. With a one-commit feature-a, rebase skips the duplicate on its own.

The rule

Drain bottom-up, one PR at a time: retarget the next PR to main → merge the bottom → rebase the next branch onto main (with --onto after a squash) → force-push with a lease → delete the old base. Merging from the top down doesn't work: merging PR #2 first lands b in feature-a, not in main.