From f3f7538d15c8db9a45547589dae6cee63eccc2b7 Mon Sep 17 00:00:00 2001 From: cluade-reviewer-andresmgsl Date: Wed, 5 Aug 2026 13:42:21 +0000 Subject: [PATCH] docs(upstream-sync): stale in-flight branches, and auditing post-merge runs by executed steps (#200) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit @codex-reviewer-andresmgsl's two additions (#5697), both measured in the #198 sync rather than anticipated. Every branch open across a sync is stale afterwards: Forgejo never re-tests an open PR when main moves under it, so #206 and #207's green 22-file suites were about a tree that no longer existed once the 28-file one landed — and #206's fragment was individually green while making the combined tree red under a rule the sync itself introduces. The runbook now says to update each in-flight branch from the newly synced main, or check them in a scratch merge, and that a prior approval is evidence about the tree it was given on. And post-merge runs are audited by executed steps, never by colour: inventory what the sync changed about triggers and jobs, read which job actually ran, and treat a green refusal path as evidence for that path only. Run 326 was green and had reconciled nothing. Both failures happened with the no-runtime-gh guard green and CI green, so the runbook says that too. Refs #200 --- changelog.d/200.md | 8 ++++-- docs/UPSTREAM-SYNC.md | 60 +++++++++++++++++++++++++++++++++++-------- 2 files changed, 55 insertions(+), 13 deletions(-) diff --git a/changelog.d/200.md b/changelog.d/200.md index 3aa9a18..ced2b20 100644 --- a/changelog.d/200.md +++ b/changelog.d/200.md @@ -17,8 +17,12 @@ wrong three times in one sync — untracked files, a pinned linter, and a pinned `jq` whose empty-input exit code differs (#200). -- It says to test the merge RESULT when other PRs are open: Forgejo tests - heads, so two green branches can produce a red tree (#200). +- It says every branch open across a sync is stale afterwards — Forgejo never + re-tests an open PR when main moves, so a prior approval is evidence about a + tree that no longer exists (#200). + +- It says to audit post-merge runs by executed steps rather than colour, and to + inventory what the sync changed about workflow triggers and jobs first (#200). - `.upstream-ref` records the upstream commit this tree carries, in machine-readable form beside the CHANGELOG's prose (#200). diff --git a/docs/UPSTREAM-SYNC.md b/docs/UPSTREAM-SYNC.md index 3393b22..f4ae16f 100644 --- a/docs/UPSTREAM-SYNC.md +++ b/docs/UPSTREAM-SYNC.md @@ -158,20 +158,58 @@ bash actions/changelog-armed/changelog-armed.sh and run the suite once under the runner's `jq` as well as your own. -**And check the merge result, not just the head.** Forgejo tests branch heads; -it never tests what two branches produce together. Two PRs can each be green -and their merge red — that happened in this sync, because a rule the sync -*introduces* (#262's terminal citation) was not met by a fragment written -against the base that lacks it. If other PRs are open, merge them together -locally and run the suite on the result. +### Every branch that was open during the sync is now stale -### 8. After it merges +Forgejo tests branch heads; it never tests what two branches produce together, +and it never re-tests an open PR when `main` moves under it. So after a sync +lands, **every PR that was open across it is green against a tree that no +longer exists** — its run did not contain the test files and rules the sync +introduced. + +Both halves of that bit in this sync: + +- `#206` and `#207` were cut from the pre-sync base. Their green suites had 22 + test files; the merged tree has 28. +- `#206`'s changelog fragment was individually green and made the **combined** + tree red, because the terminal-citation rule (#262) arrives *with* the sync + and the fragment was written against a base without it. + +So, for each PR still open: + +```sh +git merge origin/main # in the branch — do not rewrite its commits +CEREMONY_REQUIRE_NPM=1 CEREMONY_REQUIRE_YQ=1 bash test/run.sh +``` + +or, if you are only checking rather than updating, merge them into a scratch +worktree together and run the full current suite and static guards there. A +prior approval is evidence about the tree it was given on; after a sync it is +not evidence about the tree the operator would merge. + +### 8. After it merges — audit by executed steps, never by colour The sync issue uses `Refs`, not `Closes`, and stays open until a real sweep on -the merged `main` is linked to it. A green workflow run is not that evidence by -itself: verify the run actually **reconciled** something. In this sync the -first post-merge run was green and had done nothing at all, because upstream's -restructure moved reconcile behind a dispatch this forge cannot perform. +the merged `main` is linked to it. + +**A green run is not that evidence.** In this sync the first post-merge run was +green and had reconciled *nothing*: upstream's #209 restructure moved reconcile +out of the labels caller and behind a dispatch this forge cannot perform, so +the only job that ran was the refusal. Green, correct, and proof of the +refusal path only. + +So before citing any run: + +1. **Inventory what the sync changed about workflow triggers and jobs** — which + jobs exist now, which events fire them, and which of those this forge can + actually serve. A restructure upstream can move work between workflows + without touching a line of the code that does it. +2. **Read the run's executed steps**, not its status. Name the job that did the + thing, and quote the line that shows it did. +3. A green *skipped-or-refusing* path is valid evidence **for that path**, and + never evidence that the work happened. + +Neither of these is caught by the no-runtime-`gh` scan in step 4: in this sync +both failures occurred with that guard green and CI green. ## Where the forge delta lives