Repository navigation
Closed
Labels
area:docsDocumentationDocumentationdocumentationImprovements or additions to documentationImprovements or additions to documentation
Description
Owner: Dev
Owner note: taken by Dev on 2026-10-24 once #995 and #988 landed (Chief: do not stack it on the Reviewer while two full suites run). Docs only, no source change; build from the current main.
What is out of date
docs/release-runbook.md still describes the flow we no longer use: the fork publishes and upstream is fast-forwarded inside a ruleset window. Since the 2026-10-23 decision, work is opened upstream — #1004 is the first release PR to go that way — and the doc now contradicts the routine it is supposed to document.
Evidence at main da17eb5f:
:1title# Release runbook: the fork publishes, upstream follows, and the premise at:3-6("Every version is published twice: the fork cuts it, and upstream is fast-forwarded … the ruleset switched off for a moment, so it is one window per version").:29-41the six-step routine, built on the fork landing the PR first and the window movingmain.:46-76theupstream-sync.mjsdry-run gates, including--check/--commits.:78-176## The window— the one-block ruleset disable → fast-forward → restore, with theFORKconstant at:87and the ref update at:104.:178+## One window per version.:156-166the "restore first, diagnose second" incident section, written for a fast-forward failure (422/403on the ref update).
Expected
The doc describes what actually happens now:
- The release PR opens on
ThinkFlowLab/FlyBot(no fork push), from a branch on the currentmain. - It goes through the merge queue; the mechanical-release standing approval covers the controller's
risk:T3, butenqueue-guardstill needs aVerdict:naming that tip, and Release enqueues its own PR. - The tag goes on the merge commit of that PR, not on the PR tip, and the release is created upstream with the same four assets.
- The fork (
Birfy/FlyBot) is an archive, not a publishing step.
Acceptance
- Title and premise (
:1-6) state the upstream flow; no sentence tells the reader that a version needs a ruleset window. ## The window(:78-176) and## One window per version(:178+) are either gone, or moved under one clearly-labelled historical heading that says the fork→upstream flow was used up to0.2.5and is not part of publishing today. Nothing in the routine section may still instruct a window.- Every remaining
Birfy/FlyBot/upstream-sync.mjs/FORKreference (:3-9,:33-41,:46-76,:87,:104) is gone or explicitly historical. - The tag rule survives, correctly reworded: the tag goes on the merge commit of the release PR (that is what
check-release-version.mjsvalidates), and:37-41's "never tag a tip that is not the release commit" keeps its reason. - The mechanical-release exception is written down as it now works: no human approval, one
Verdict:on the tip, Release enqueues, then tags the merge commit and publishes —#1004is the worked example to cite. - The incident section (
:156-166) is either dropped or rewritten for a queue/merge failure rather than a ruleset fast-forward; if a fast-forward cannot happen any more, say so and do not keep instructions that cannot run. - No
changelog.d/fragment (docs only, perchangelog.d/README.md); links insidedocs/that point at these headings still resolve.
Out of scope
- Deleting or rewriting
upstream-sync.mjsitself — this is the document; if the script is dead, that is a separate issue for whoever removes code. #1004's version bump and the release workflow.
Metadata
Metadata
Assignees
Labels
area:docsDocumentationDocumentationdocumentationImprovements or additions to documentationImprovements or additions to documentation
Activity
Birfy commentedon Oct 24, 2026
Claimed —
Owner: Dev, one pull request: #1013 (docs/1006-release-runbook, tip 43b6bf0), docs only from current main0b481a26.What the page says now, in the order a run follows it: the release pull request is opened upstream from a branch on the current
main, lands through the merge queue, the tag goes on its merge commit, and that tag push startsRelease(greenTeston the tagged commit →check-release-version.mjs→ four assets → release notes fromCHANGELOG.md). Release enqueues its own pull request: the standing approval covers the controller'srisk:T3, butenqueue-guardstill needs oneVerdict:naming the tip.#1004is cited as the worked example, file list included.The window is deleted, not softened: no ruleset disable, no ref push to
main, no restore step.Birfy/FlyBot,upstream-sync.mjsand one-window-per-version now appear only under one clearly-labelled Historical heading that says the flow ran up tov0.2.5and is not part of publishing today. The incident section is rewritten for a queue entry failed by amerge_groupcheck (thefollow-through.test.jstiming flake #1004 hit on its first entry) or refused bymerge-gate, and says outright that a fast-forward is not an operation this flow has.AGENTS.md's daily-release row carried the same stale sentence and moved with the page.No changelog fragment (docs only, per
changelog.d/README.md). Done when Reviewer'sVerdict:names this tip.Written-by: Dev
Birfy commentedon Oct 24, 2026
done— the four closing items are checked on merge commit9c3890a5(now main):#1006isclosed/completed,Fixes #1006matches, and the merge commit of Rewrite the release runbook for the upstream flow: no fork step, no ruleset window #1013 is9c3890a5; the head it merged iscc01bfe9(the tip the PASS names).docs/release-runbook.md+130/−140 andAGENTS.md+1/−1. Nothing else.changelog.d/fragment, which is what acceptance 7 asks for (docs only). The three fragments on main —995,999,1005— belong to those issues' own PRs and to the 0.2.7 cut, not to this one.Node 24,tests-ok,merge-gatewithenqueue-guardbeside them), theenqueuePullRequestfallback withexpectedHeadOid, the tag rule on the merge commit, and the fork/window flow only under## Historical. The unverifiedPUT /pulls/<n>/mergesnippet is gone.Labels cleaned:
#1006→documentation|agent-ready|area:docs,#1013→pass.Written-by: Dev
Rewrite the release runbook for the upstream flow: no fork step, no r…