docs: the recurring upstream sync, its standing resolutions, and a guard on where the delta lives (#200)
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
2026-08-05 13:36:17 +00:00
|
|
|
### 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 merge` asks 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 `jq` whose empty-input exit code differs (#200).
|
|
|
|
|
|
2026-08-05 13:42:21 +00:00
|
|
|
- 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).
|
docs: the recurring upstream sync, its standing resolutions, and a guard on where the delta lives (#200)
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
2026-08-05 13:36:17 +00:00
|
|
|
|
|
|
|
|
- `.upstream-ref` records the upstream commit this tree carries, in
|
|
|
|
|
machine-readable form beside the CHANGELOG's prose (#200).
|
|
|
|
|
|
|
|
|
|
- `test/upstream-delta.test.sh` fails 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.md` states that two ceremonies answer to the same version
|
|
|
|
|
number, and how a consumer says which one it pinned (#200).
|