docs(upstream-sync): stale in-flight branches, and auditing post-merge runs by executed steps (#200)
All checks were successful
CI / test (pull_request) Successful in 3m2s
CI / release-exercise (pull_request) Successful in 10s
CI / self-guards (pull_request) Successful in 6s
CI / action-exercise (pull_request) Successful in 6s
CI / docs-sync-exercise (pull_request) Successful in 6s
Refs guard / refs-not-closing (pull_request) Has been skipped
labels / labels (pull_request) Successful in 8s
All checks were successful
CI / test (pull_request) Successful in 3m2s
CI / release-exercise (pull_request) Successful in 10s
CI / self-guards (pull_request) Successful in 6s
CI / action-exercise (pull_request) Successful in 6s
CI / docs-sync-exercise (pull_request) Successful in 6s
Refs guard / refs-not-closing (pull_request) Has been skipped
labels / labels (pull_request) Successful in 8s
@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
This commit is contained in:
parent
e965b15cbf
commit
f3f7538d15
2 changed files with 55 additions and 13 deletions
|
|
@ -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).
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue