Skip to content

fix(release): name the changes a tag carried but its notes assembled too early to see - #1215

Open
HugoXK wants to merge 1 commit into
mainfrom
dev2/1207-stranded-notes
Open

HugoXK wants to merge 1 commit into
mainfrom
dev2/1207-stranded-notes

Conversation

@HugoXK

@HugoXK HugoXK commented Nov 21, 2026

Copy link
Copy Markdown
Owner

Written-by: Fledge Platform Dev-2

Fixes #1207

What changed

scripts/release-stranded-notes.mjs + scripts/lib/stranded-fragments.mjs (new). The publish run reads changelog.d/ at the tagged tree with the existing rule (fragmentNames, which throws rather than answering zero, #548). A fragment still present there is by construction a change the release carries and its notes were assembled too early to name, so the body gains one section below the assembled notes:

## Changes that merged after these notes were assembled

These changes merged into `main` while this release waited to be merged, so the tag ships them even though the notes above were assembled before they arrived. They are part of this release:

- <the fragment's own text>

.github/workflows/release.yml

  • New step Name the changes that merged after the notes were assembled (id: stranded), after the existing-release guard and before Build the image, gated on published != 'true'. It fails the run on an unreadable changelog.d, so no image and no release is published from a body that would read complete without the release's own changes.
  • The notes file is ${RUNNER_TEMP}/release-notes.md in all four steps that touch it (assemble, stranded section, chain lines, gh release create). The hard-coded /tmp path made the step impossible to drive outside a runner, and one variable is also one path.
  • New job stranded-log (needs: release, if: needs.release.outputs.stranded != '', permissions: issues: write only) posts the one #80 line that names the fragments, with a marker keyed on tag + fragment set so a re-dispatch of one tag repeats nothing. It is a separate job because the publish job's token holds contents, packages, id-token and attestations write and must not gain a scope it never uses; the release job exposes the names as a job output. An ordinary night leaves the job skipped; a tag that already has a release never reaches the step that fills the output.

test/releasePublishGuard.test.ts — the step splitter is now job-scoped: the workflow has a second job, so "everything after the notes step" is no longer the publish job. The assertions are unchanged and still cover exactly the publish job's steps.

docs/deploy.md gains the mechanism paragraph; a stranded fragment is still folded into the next release, so a change can be named twice until the fold itself is reworked (the card's known consequence, left as it is).

Red first, at the base

test/releaseStrandedFragments.test.ts drives the real step body out of release.yml, the way test/releasePublishGuard.test.ts drives the guard. At the base 044c7515a6111560bf96cdd20e8c724535cefc0a, with only the new test file on an otherwise clean tree (scripts/ and the workflow untouched):

npx tsx --test test/releaseStrandedFragments.test.ts
# tests 6   # pass 0   # fail 6
  • the stranded fixture never gains the section — the step does not exist at the base, so the fragment's text appears nowhere in the assembled body;
  • the clean fixture has nothing to compare against, the unreadable changelog.d is not refused by the workflow, the chain-line case has no section to survive, and the step-gating and #80-job assertions have no step or job to read.

The fragment body in the red test is a real sentence, and the test asserts it lands below the assembled notes, not that a string exists somewhere in the body.

At the tip

7557fb618290637279cb78b63b6976f37d93a741, tree d0eccc52a2b01d8a21913204cdfd0478b5eaf71b, parent 044c7515a6111560bf96cdd20e8c724535cefc0a, 7 files +453/−5.

npx tsx --test test/dailyRelease.test.ts test/releasePublishGuard.test.ts \
  test/changelogFragments.test.ts test/supplyChain.test.ts \
  test/releasePublishToken.test.ts test/releaseChain.test.ts \
  test/releaseStrandedFragments.test.ts   → 89 passed, 0 failed
npm run check                             → exit 0

npm run check at the tip: lint 11 warning(s) in 8 entries match the baseline, typecheck clean, # tests 3299 / # pass 3299 / # fail 0, build clean. node scripts/changelog.mjs check → every fragment ok.

The four cases the card asks for

  1. Stranded case — a fixture tree whose changelog.d/ holds README.md plus 999.fixed.md: the section is appended, names the fragment's own text, and sits below the assembled body. README.md is never a fragment.
  2. Clean case — README.md only: the notes file is byte-identical, the output is names= (empty) and the summary says the tag stranded nothing.
  3. Unreadable directory — changelog.d that cannot be read (a regular file at that path, so it fails for any user, not only a non-root one): the step exits non-zero, appends nothing, and stderr names the directory. The step sits before the build, so the image is never published from that body.
  4. Chain lines survive — a stranded fragment whose sentence contains a Image: …@sha256:…-shaped string is appended first, then the real chain step runs, and publishedChainFromBody from scripts/verify-release.mjs reads the image, SBOM and attestation lines exactly as before, with the section still above them.

Risk tier

node scripts/risk-gate.mjs --base 044c7515 at the shipping tree, verbatim:

changed files: 7

T3: .github/workflows/release.yml, scripts/lib/stranded-fragments.mjs, scripts/release-stranded-notes.mjs
T1: test/releasePublishGuard.test.ts, test/releaseStrandedFragments.test.ts
T0: changelog.d/1207.fixed.md, docs/deploy.md
limits: 40 files / 1200 lines (advisory)

risk-tier: T3; basis: .github/workflows/release.yml

T3, so this needs a seat PASS at this tip plus green ci-ok, and the Gate Security read on the same tip: the diff adds issues: write to a new job that does nothing but post one comment, and adds no scope to the publish job.

Alternatives considered

  • Refuse to publish when a fragment is stranded. Rejected on the card: it dead-ends the night after the release pull request has merged and stops the daily cadence on notes hygiene.
  • Re-assemble the notes at merge time. Rejected on the card: that writes to the release branch after its checks ran and is the follow-up card's design decision, not this slice.
  • Hand-fold the three v0.4.5 fragments into the published section. Rejected on the card: it edits a published release's record by hand and leaves the mechanism in place.
  • Post the #80 line from the publish job. Rejected: the publish token holds four write scopes and would gain a fifth it never uses; a separate job with issues: write alone keeps the publish token at its current set.
  • Append the section from the existing "Record the published chain" step. Rejected: that step's whole job is the three chain lines the verification reads back; mixing in a second concern makes both harder to test and to reason about.
  • Write the section into CHANGELOG.md. Rejected: the tagged tree is what gh release create publishes, and the card keeps CHANGELOG.md untouched.

Uncertainty and residual risk

  • A fragment stranded at the tag is still folded into the next release's section, so a change can be named twice until the fold is reworked. This PR makes the published notes honest; it does not deduplicate.
  • The #80 line runs after the release job; if it fails, the release is already published (correct notes) and the run is red. It is a comment, not a gate.
  • A stranded fragment whose file is unreadable for a reason other than the directory (permissions on the file) also fails the step, which is the intended loud failure.
  • The bounded window this closes is only the publish side: the release pull request can still wait for hours, and the next release can still fold the same fragment. That is the follow-up card.

Rollback

Revert the commit. The publish path returns to assembling CHANGELOG.md's section alone, the #80 job disappears, and the notes file path returns to /tmp/release-notes.md. Nothing is persisted; the step only appends to a file inside the run.

UI surface

None — a workflow step and its CLI. No page, string, asset or control changes, so no before/after frame applies.

Docs and changelog

docs/deploy.md gains the mechanism paragraph. changelog.d/1207.fixed.md carries the user-visible line: the notes now name every change the tag carries. No Docs-not-needed: claim.

Ran:

  • npx tsx --test test/releaseStrandedFragments.test.ts at the base 044c7515 with scripts/ and the workflow untouched — # tests 6 / # pass 0 / # fail 6 (the red above)
  • npx tsx --test test/dailyRelease.test.ts test/releasePublishGuard.test.ts test/changelogFragments.test.ts test/supplyChain.test.ts test/releasePublishToken.test.ts test/releaseChain.test.ts test/releaseStrandedFragments.test.ts at the tip — 89 passed, 0 failed
  • npm run check at the tip — exit 0 (# tests 3299 / # pass 3299 / # fail 0, lint at baseline, typecheck and build clean)
  • node scripts/changelog.mjs check at the tip — every fragment ok
  • node scripts/risk-gate.mjs --base 044c7515 — risk-tier: T3; basis: .github/workflows/release.yml
  • the seven changed blobs read back from the remote commit through the Git Data API and compared with this tree — tree d0eccc52a2b01d8a21913204cdfd0478b5eaf71b, identical

Not run:

  • a real tag publish (this needs the release workflow, and no tag is created here)
  • actionlint / the workflow-lint job locally: the YAML is exercised by the suite's step-body drivers and by test/supplyChain.test.ts, but the pinned actionlint binary is a CI step
  • the #80 comment itself against the live API: the job body is syntax-checked (bash -n) and its marker/dedupe shape is asserted, but no comment is posted by this PR
  • the GitHub Release body on a real tag, and the docker image

…too early to see

A release's notes are assembled once, when the release pull request is built, and
nothing reads changelog.d/ again before the tag is written. Every change merged
into main while that pull request waited rides in the tag and is missing from the
notes the tag publishes; v0.4.5 shipped three that way while its pull request
body reported 22 fragments.

The publish run now reads changelog.d at the tagged tree with the existing rule
and, when a fragment is still there, appends one section naming each of them
below the assembled notes. The step runs before the image is built and fails on
an unreadable directory, so no image or release is published from a body that
would read complete without the release's own changes. The fragment names are
said on #80 by a separate job that holds issues: write and nothing else, so the
release log and the published notes agree.

test/releaseStrandedFragments.test.ts drives the real step body out of
release.yml: the stranded fixture gains the section, the clean fixture is
byte-identical, an unreadable changelog.d fails without appending, and the three
chain lines still parse after the section. At the base the step does not exist,
so all six fail.

Written-by: Fledge Platform Dev-2

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

agent-pr area:deploy Deploy, backup, logs, systemd bug Something isn't working risk:T3

Projects

None yet

Development

Successfully merging this pull request may close these issues.

release: a tag's notes omit every change merged while its release pull request waited

1 participant