Skip to content

Rewrite docs/release-runbook.md for the upstream release flow: no fork, no ruleset window #1006

Closed

Description

@Birfy

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:

  • :1 title # 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-41 the six-step routine, built on the fork landing the PR first and the window moving main.
  • :46-76 the upstream-sync.mjs dry-run gates, including --check / --commits.
  • :78-176 ## The window — the one-block ruleset disable → fast-forward → restore, with the FORK constant at :87 and the ref update at :104.
  • :178+ ## One window per version.
  • :156-166 the "restore first, diagnose second" incident section, written for a fast-forward failure (422 / 403 on the ref update).

Expected

The doc describes what actually happens now:

  1. The release PR opens on ThinkFlowLab/FlyBot (no fork push), from a branch on the current main.
  2. It goes through the merge queue; the mechanical-release standing approval covers the controller's risk:T3, but enqueue-guard still needs a Verdict: naming that tip, and Release enqueues its own PR.
  3. 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.
  4. The fork (Birfy/FlyBot) is an archive, not a publishing step.

Acceptance

  1. Title and premise (:1-6) state the upstream flow; no sentence tells the reader that a version needs a ruleset window.
  2. ## 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 to 0.2.5 and is not part of publishing today. Nothing in the routine section may still instruct a window.
  3. Every remaining Birfy/FlyBot / upstream-sync.mjs / FORK reference (:3-9, :33-41, :46-76, :87, :104) is gone or explicitly historical.
  4. The tag rule survives, correctly reworded: the tag goes on the merge commit of the release PR (that is what check-release-version.mjs validates), and :37-41's "never tag a tip that is not the release commit" keeps its reason.
  5. 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 — #1004 is the worked example to cite.
  6. 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.
  7. No changelog.d/ fragment (docs only, per changelog.d/README.md); links inside docs/ that point at these headings still resolve.

Out of scope

  • Deleting or rewriting upstream-sync.mjs itself — 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.

Activity

  1. added
    documentationImprovements or additions to documentation
    agent-readyMaintainer-approved spec: an agent may take it. Only maintainers set this; never in a template
    agent-workingAn agent has claimed this issue (the claim comment names the branch)
    on Oct 24, 2026
  2. self-assigned this
    on Oct 24, 2026
  3. Birfy commented on Oct 24, 2026

    @Birfy
    CollaboratorAuthor

    Claimed — Owner: Dev, one pull request: #1013 (docs/1006-release-runbook, tip 43b6bf0), docs only from current main 0b481a26.

    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 starts Release (green Test on the tagged commit → check-release-version.mjs → four assets → release notes from CHANGELOG.md). Release enqueues its own pull request: the standing approval covers the controller's risk:T3, but enqueue-guard still needs one Verdict: naming the tip. #1004 is 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.mjs and one-window-per-version now appear only under one clearly-labelled Historical heading that says the flow ran up to v0.2.5 and is not part of publishing today. The incident section is rewritten for a queue entry failed by a merge_group check (the follow-through.test.js timing flake #1004 hit on its first entry) or refused by merge-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's Verdict: names this tip.

    Written-by: Dev

  4. removed
    agent-workingAn agent has claimed this issue (the claim comment names the branch)
    on Oct 24, 2026
  5. Birfy commented on Oct 24, 2026

    @Birfy
    CollaboratorAuthor

    done — the four closing items are checked on merge commit 9c3890a5 (now main):

    • #1006 is closed/completed, Fixes #1006 matches, and the merge commit of Rewrite the release runbook for the upstream flow: no fork step, no ruleset window #1013 is 9c3890a5; the head it merged is cc01bfe9 (the tip the PASS names).
    • The diff is docs only: docs/release-runbook.md +130/−140 and AGENTS.md +1/−1. Nothing else.
    • No 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.
    • What landed is the corrected page, not only a reworded title: main has the three required checks (Node 24, tests-ok, merge-gate with enqueue-guard beside them), the enqueuePullRequest fallback with expectedHeadOid, the tag rule on the merge commit, and the fork/window flow only under ## Historical. The unverified PUT /pulls/<n>/merge snippet is gone.

    Labels cleaned: #1006 → documentation|agent-ready|area:docs, #1013 → pass.

    Written-by: Dev

  6. removed
    agent-readyMaintainer-approved spec: an agent may take it. Only maintainers set this; never in a template
    on Oct 24, 2026
  7. added a commit that references this issue on Oct 24, 2026
    9c3890a
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

area:docsDocumentationdocumentationImprovements or additions to documentation

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions