docs(release): document the CI approval, the revert: subject, and correct the pipeline's own account of itself

[IgorShevchik]

Linked issue

Closes #353.

Type of change

• Documentation (updates to the documentation or readme)
• Bug fix (a non-breaking change that fixes an issue)
• Enhancement (improving an existing functionality)
• New feature (a non-breaking change that adds functionality)
• Chore (updates to the build process or auxiliary tools and libraries)
• Breaking change (fix or feature that would cause existing functionality to change)

Description

Five review passes found the first revision of this PR wrong in ways that mattered — most sharply, it told the reader the opposite of what they would be looking at. This revision fixes the false claims the pipeline makes about itself rather than only adding true ones beside them.

The symptom is stated correctly now

The first revision opened with "the release PR will sit at blocked with no ci check". The API contradicts it: get_check_runs on #356 returns exactly one check run — ci, success. A held run creates no jobs and therefore no check run, so the held one is invisible while the dispatched one is green.

That mattered beyond accuracy. Green check + refused merge is also what a stale branch looks like, so the wrong symptom routed the reader to the wrong remedy. Both causes are now documented, in the order to check them, with the literal string someone will search on:

Required status check "ci" is expected

The click is a procedure with an order

• Actions → the held run is the primary route. The Checks tab is not — a held run renders nothing there, so a reader following the old instruction would have found one green ci and concluded the doc was stale.
• The button has been labelled both Approve and run and Approve workflows to run; both are given.
• Approval attaches to a run, and a run to a commit. Any push to main strands it — up to nine held runs in a day here, not the four first claimed, which was the lowest day in the sample presented as typical. That makes approve-then-merge a race rather than a sequence, so the doc now says merges to main pause while the run is in flight, and says what to do if one lands anyway.

Two workflow comments asserted the mechanism this document refutes

ci.yml and release-please.yml both claimed a GITHUB_TOKEN PR fires no pull_request event and that the dispatched run satisfies the required check. Neither is true, and they are the files a person opens first when the PR is stuck. Both corrected and pointed at the new section — the same discipline release-watchdog.yml already applies to the cadence commitment ("keep the two in sync").

Leaving them was the largest gap in the first revision: #353 explicitly asks for that comment to be corrected, so closing the issue without touching it would have left its named artifact lying in the tree.

The revert guidance now names where the subject is actually set

Retitling the PR may not be enough. A revert PR is always a single commit, and for single-commit PRs GitHub may take the squash subject from the commit rather than the title — evidence in this repo (167cd6f3, PR #439) points that way. The squash-merge dialog is the route that works either way.

Three things added because they change what a reader does:

• the parse failure is not silent — commit could not be parsed: <sha> Revert "…" prints in the Release Please job log every run. The first revision said no error exists anywhere, which removes the one diagnosis available.
• a Revert "…" that is the only commit since the last tag opens no release PR at all.
• a revert: does not cancel the feat: it undoes — both appear and the release is still a minor.

The two revert commits are no longer offered as evidence

The first revision cited 8b774dcd and 2cc874e2 as proof of harm. Both predate bootstrap-sha and the CHANGELOG's first entry by 18 days, so no changelog generator ever saw them — a disqualifier stated in #435's own commit message and dropped here. The sample of reverts under release-please is zero; the doc now says so, which is also the honest reason to write this down before the first one rather than after.

The template is where the trap is catchable

GitHub's revert button opens the PR form with Revert "…" already in the title box. That is the screen, at the moment, so the instruction goes there — plus a Revert row in Type of change — rather than only into guides nobody has open then.

The watchdog's nudge reaches a maintainer exactly when their release PR is stuck; it said "Merging it tags, releases and publishes" and now links the approval section.

Corrected in passing

• Optional hardening claimed merging is "the only human step" — contradicting this file's own opening, 200 lines apart.
• The severity:crash explanation existed twice, near-verbatim, in two places that must stay in sync.
• "the promise below" pointed at the 14-day commitment; the referent is the 48-hour one, 30 lines further down.
• Two paragraphs about release cadence had been orphaned under a heading about repository settings — a structural regression invisible in the previous diff, since their text was untouched.
• Branch protection was missing from the list of settings the pipeline depends on, though it is the setting that causes the symptom.
• The break-glass omitted pnpm run dev:prepare and --no-git-checks, without which it ships a tarball missing .nuxt/b24ui.static.css — a file package.json lists in files.

"No workflow-file fix" is now "none worth taking"

One does work: a workflow can POST /repos/{owner}/{repo}/statuses/{sha} with context: ci, and a commit status satisfies a required check exactly as a check run does. It is refused on purpose — it fabricates the signal the gate exists to carry — and that reason is now recorded next to the trick, so the next person finds both. merge_group and the Actions approval setting are listed as unexplored, not impossible.

Verification

check	result
test/workflows/run.sh	49 passed, 0 failed
test/utils/documented-scripts.spec.ts	8/8 — and it caught a real defect: prose reading pnpm refuses to publish parsed as a script invocation
assert-actions-pinned.py	all actions SHA-pinned
shellcheck -x -S warning	clean
YAML parse, both workflows	valid
eslint .	clean
internal anchors in releasing.md	all resolve, including the three now referenced from workflows and scripts

Checklist

• I have linked an issue or discussion.
• I have updated the documentation accordingly.