cluade-reviewer-andresmgsl
e965b15cbf
The third child of #197, written immediately after performing the sync it describes, while the findings are still first-hand. docs/UPSTREAM-SYNC.md carries the procedure and the six standing resolutions, each with the issue that decided it, so they are not re-argued every sync. The parts that are not obvious from the outside, and that the 0.6.0 sync paid to learn: * THE AUDIT STEP. `git merge` takes upstream's side wherever only upstream moved a region, so a function upstream ADDED to a file this tree owns arrives with no conflict and no question. Reviewing the hunks cannot find it — four reviewers read the same diff and each found a different subset. That was eight runtime `gh` call sites in three files and two file types. * THE SAME MECHANIC APPLIES TO STATE. A resolved region can remove a producer whose consumers auto-merged, and those consumers degrade to empty rather than erroring, so nothing goes red. Three such seams in one sync. * VERIFY WHERE IT RUNS. "Green locally" was wrong three times, for three different reasons: shellcheck-all lints TRACKED files so a new file's first lint is meaningless; CI pins shellcheck 0.10.0; and the runner's jq 1.6 exits 0 where 1.7 exits 4 on `jq -e` with empty input — which was not a test problem but a guard accepting an unreadable read. * TEST THE MERGE RESULT. Forgejo tests heads, never what two branches produce together, and two green PRs did produce a red tree in this sync. * AFTER MERGING, CHECK THE SWEEP RECONCILED SOMETHING. The first post-merge run was green and had done nothing. .upstream-ref records the carried commit in machine-readable form beside the CHANGELOG's prose. test/upstream-delta.test.sh asserts every forge-DECIDING file is named in the inventory — offline, comment-aware, and refusing rather than skipping when the ref is missing. Shim CONSUMERS are allowed by name, so a seventh consumer is silent and a seventh decider is not. docs/CONSUMERS.md now states that two ceremonies answer to the same version number and how a consumer says which one it pinned. Must-fail, both from the issue's test plan: scattering a forge_detect branch into an unlisted file reds the guard; blanking .upstream-ref reds it too. test/run.sh 29 files 0 failed under jq 1.7 and jq 1.6; shellcheck 0.10.0, actionlint, self-ref, marker, vendored and changelog-armed all clean. Refs #200
1.4 KiB
Added
-
docs/UPSTREAM-SYNC.md— the recurring upstream sync as a runbook: the standing resolutions, which side wins each and the issue that decided it (#200). -
It names the step the 0.6.0 sync nearly shipped without: auditing what the merge brought in that did not conflict.
git mergeasks no question about a function upstream added to a file this tree owns (#200). -
It records that the same mechanic applies to state, not just to call sites: a resolved region can silently remove a producer whose consumers auto-merged, and every one of those consumers degrades to empty rather than erroring (#200).
-
It says to verify with the runner's tooling, because "green locally" was wrong three times in one sync — untracked files, a pinned linter, and a pinned
jqwhose 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).
-
.upstream-refrecords the upstream commit this tree carries, in machine-readable form beside the CHANGELOG's prose (#200). -
test/upstream-delta.test.shfails the PR that scatters forge branching into a file the inventory does not name — offline, and refusing rather than skipping when the recorded ref is missing (#200). -
docs/CONSUMERS.mdstates that two ceremonies answer to the same version number, and how a consumer says which one it pinned (#200).