docs: record merge-method requirement and divergence recovery in release playbook

[bpamiri]

Playbook corrections learned at the 4.0.3 cut (#2892):

• The "merge with a merge commit" step silently depended on the repo setting Allow merge commits, which had been switched to squash-only between the 4.0.1 and 4.0.2 cuts — forcing Release 4.0.2 #2819 to squash and poisoning the next promotion with 24 spurious conflicts. The setting is enabled again (permanently, per maintainer decision 2026-06-09); the playbook now states the dependency explicitly.
• Documents the -s ours healing recipe for promoting develop over a diverged main, including the must-be-empty tree-diff verification step.
• Promote the CHANGELOG rename on develop before cutting the release branch (the 4.0.3 flow, docs(changelog): reconcile and promote [Unreleased] to [4.0.3] #2891), so develop doesn't need a docs(changelog): promote develop [Unreleased] to [4.0.2] #2824-style back-port.
• Fixes dispatch-list drift: chocolatey-wheels → scoop-wheels (retired for v4; scoop-wheels#4), and adds the missing apt/yum bucket dispatches.

Docs-only; no executable paths touched.

🤖 Generated with Claude Code

[wheels-bot]

Wheels Bot — Reviewer A

TL;DR: Docs-only patch documenting three lessons from the 4.0.3 cut: the "Allow merge commits" repo-setting dependency, the `-s ours` divergence-healing recipe, the CHANGELOG-rename-on-develop sequencing, and a corrected dispatch list. The dispatch corrections are verified against `release.yml` and the prose is accurate. Two gaps in the `-s ours` recipe make it incomplete for the intended 3am use-case; flagging as nits. Overall verdict: comment — the core content is correct, but the recipe needs two lines to be safely executable.

---

Correctness

Gap 1 — git checkout -b fails if the branch already exists.

.github/RELEASE_PLAYBOOK.md, the new conflict-recovery bash block:

git checkout -b release/X.Y.Z-to-main origin/develop

The section heading is "If the develop→main PR reports conflicts", meaning the normal flow (step 1 of the release day section) has already run: the branch was created, pushed, and the PR was opened. At that point git checkout -b fails with fatal: A branch named 'release/X.Y.Z-to-main' already exists. Replace -b with -B to reset the branch to origin/develop:

git checkout -B release/X.Y.Z-to-main origin/develop

Gap 2 — No git push step after the merge.

The same bash block ends with:

git diff HEAD origin/develop    # MUST print nothing — verify before pushing

The comment says "before pushing", but there is no push command. After the verify the remote branch and the open PR still reflect the old (conflicting) head. The block needs:

git push --force-with-lease origin release/X.Y.Z-to-main

Without it a maintainer following the recipe will see their local state is correct but the GitHub PR will still report conflicts, and gh pr merge --merge will refuse.

Suggested final block:

git checkout -B release/X.Y.Z-to-main origin/develop
git merge -s ours origin/main -m "Merge main into release branch (ours): develop is authoritative"
git diff HEAD origin/develop    # MUST print nothing — verify before pushing
git push --force-with-lease origin release/X.Y.Z-to-main

---

Commits

Single commit docs: record merge-method requirement and divergence recovery in release playbook — 81 characters, docs type, no scope (optional), not ALL-CAPS. Passes commitlint.config.js. Clean.

---

Docs

The dispatch-list corrections (DOWNSTREAM_DISPATCH_TOKEN / LINUX_REPO_DISPATCH_TOKEN, chocolatey → scoop, apt-wheels / yum-wheels additions) were verified against .github/workflows/release.yml lines 553–736; the playbook now matches the workflow exactly.

[wheels-bot]

Wheels Bot — Reviewer B (round 1)

A's review is accurate and well-grounded. Both gaps are real, both are verified against the actual diff, and the dispatch-list check was confirmed against the exact workflow lines. No false positives, no sycophancy. The only nit B would add (a missing git fetch origin before the checkout) is minor. A's verdict is COMMENTED rather than REQUEST_CHANGES, which is lenient but defensible for a docs-only PR — the findings are concrete and actionable either way. Converging on changes needed.

Sycophancy

None detected. A withheld approval, raised two concrete gaps, and did not use LGTM language.

False positives

None detected.

• Gap 1 (-b to -B): The diff confirms the recovery recipe uses git checkout -b release/X.Y.Z-to-main origin/develop. The normal flow section preceding it includes gh pr create --base main --head release/X.Y.Z-to-main, which requires the branch to have already been created and pushed. By the time a maintainer reaches the conflict-recovery section, the local branch already exists. -b fails; -B is correct. Finding stands.
• Gap 2 (missing push): The diff confirms the bash block ends at git diff HEAD origin/develop # MUST print nothing — verify before pushing. The comment references pushing but no push command follows. A's suggested addition of git push --force-with-lease origin release/X.Y.Z-to-main is correct and necessary. Finding stands.
• Dispatch verification: Confirmed against release.yml. DOWNSTREAM_DISPATCH_TOKEN is used for homebrew/scoop and bump-develop; LINUX_REPO_DISPATCH_TOKEN for apt-wheels/yum-wheels. chocolatey-wheels is absent; scoop-wheels, apt-wheels, and yum-wheels are present. The playbook now matches the workflow.

Missed issues

One micro-nit A did not raise: the recovery block starts with git checkout -b ... origin/develop without a preceding git fetch origin. If the maintainer's local refs are stale, the branch would start at an older point, and git diff HEAD origin/develop would not print nothing even after a correct -s ours merge. Adding git fetch origin as the first line would make the recipe safe without reservation. This is minor and does not block convergence.

Verdict alignment

A issued COMMENTED (not REQUEST_CHANGES) with two concrete, actionable findings. For a docs-only PR this is defensible — both findings are explicit enough that address-review can act on them. Consistent.

Convergence

Aligned. A and B agree: the core content is correct and the dispatch corrections are verified; two lines in the conflict-recovery bash block are missing or wrong. Emitting converged-changes to trigger address-review to apply A's suggested corrections (and the git fetch origin nit if address-review judges it worthwhile).