Skip to content

fix(release): let the changelog rollover cut release candidates - #1568

Merged
lusoris merged 2 commits into
masterfrom
fix/release-rollover-rc-versions
Sep 26, 2026
Merged

lusoris merged 2 commits into
masterfrom
fix/release-rollover-rc-versions

Conversation

@lusoris

@lusoris lusoris commented Sep 26, 2026 •

Copy link
Copy Markdown
Contributor

Summary

The 1.0.0-rc.1 release PR (#1213) could merge but never publish. The tag-time verifier (scripts/release/verify-release-version.sh) accepts vX.Y.Z-rc.N tags since ADR-1201. For an RC tag it still demands the full changelog cut:

  • a ## [1.0.0-rc.1] - YYYY-MM-DD heading;
  • a changelog.d/releases/1.0.0-rc.1.json receipt;
  • zero active fragments;
  • no surviving release-as / bootstrap-sha.

The only tool that produces those, scripts/release/rollover-changelog-fragments.sh, refused anything but X.Y.Z. It also read an -rc.N version marker as its X.Y.Z prefix, the same extractor bug ADR-1201 fixed in the verifier.

This PR:

  • makes the rollover accept exactly the verifier's version shape and use its marker extractor;
  • adds three test cases:
    • an RC cut that the verifier then accepts end to end;
    • the refused prerelease shapes (-beta, -rc, -rc.01, -rc.1.2, -RC.1, -rc.-1);
    • the triple/RC boundary in both directions;
  • documents the RC cut in the release guide, plus the docs/changelog-archive path the rollover writes for a long body;
  • documents that later candidates need a Release-As: 1.0.0-rc.N footer. With versioning: default, release-please bumps a fix on 1.0.0-rc.1 to 1.0.1-rc.1, because PatchVersionUpdate keeps the prerelease tag.

A dry-run cut of #1213 exposed four more failures on the cut commit itself, fixed in the second commit:

  • The archived changelog index ended CHANGELOG.md with a blank line when no older release section exists (a first release), which end-of-file-fixer rejects. New rollover test T17 covers this, and it fails against the first commit's script.
  • check-issue-reference-provenance.py and test_research_digest_ids.py read changelog fragments that the cut deletes. The checker's new contract_text() follows consumed fragments and CHANGELOG.md prose into CHANGELOG.md plus docs/changelog-archive/. It does this only once a cut receipt exists; a missing fragment with no receipt still fails. The research-digest test reuses that resolver and checks the legacy link target. New provenance tests cover a followed cut, a missing receipt, and prose that is both inline and archived.
  • Retired ADR-0864 listed a fragment as evidence. Its two ADR files remain as evidence.

With both commits overlaid on #1213's head, the dry-run cut passes:

  • rollover --version 1.0.0-rc.1, which rolls 2,034 sources into a 21-line index and a 32,327-line archive;
  • the full pre-commit suite over the cut;
  • verify-release-version.sh v1.0.0-rc.1, run against a local-only tag that was deleted afterwards.

After this merges, #1213 regenerates. It then gets the autorelease: cut label and the rollover commit, and merges.

Type

  • Bug fix (release tooling; no scoring change)

Checklist

  • Commits follow Conventional Commits.
  • Pre-commit and the pre-push gate passed locally.
  • No public C API, CLI flag or FFmpeg patch surface changes.

Bug-status hygiene

  • docs/state.md updated in this PR: T-RELEASE-ROLLOVER-RC-VERSION-2026-09-26 added under Recently closed.

Netflix golden-data gate

  • No Netflix assertAlmostEqual(...) value was modified.

Deep-dive deliverables

  • Research digest — no digest needed: trivial (the evidence is the two scripts and the release-please PatchVersionUpdate source, cited in the release guide).
  • Decision matrix — no alternatives: only-one-way fix (the verifier from ADR-1201 already fixes the required cut; the rollover now matches it).
  • AGENTS.md invariant note — scripts/release/AGENTS.md: version shape and marker extractor must match the verifier; later RCs need Release-As.
  • Reproducer / smoke-test command — below.
  • CHANGELOG fragment — changelog.d/fixed/release-rollover-rc-versions.md.
  • Rebase note — docs/rebase-notes.md entry "Release-candidate changelog rollover (2026-09-26)".

Reproducer

bash scripts/release/tests/test-rollover-changelog-fragments.sh   # 18 passed
# On master before this PR the new RC-cut case fails:
#   FAIL: release candidate is cut with its own heading, receipt and retired fields
GIT_CONFIG_GLOBAL=/dev/null bash scripts/release/tests/test-verify-release-version.sh   # 25 passed
python3 -B scripts/ci/tests/test_issue_reference_provenance.py
python3 -B scripts/ci/tests/test_research_digest_ids.py

The verifier suite needs GIT_CONFIG_GLOBAL=/dev/null only on hosts with tag.gpgsign=true, because its fixtures create unsigned tags.

verify-release-version.sh accepts vX.Y.Z-rc.N tags (ADR-1201) but still
requires the full changelog cut for them: a versioned heading, a receipt,
no active fragments and no one-shot release-please fields. The rollover
that produces those accepted only X.Y.Z and read an -rc.N version marker
as its X.Y.Z prefix, so the 1.0.0-rc.1 release PR could merge but never
publish.

The rollover now accepts the verifier's exact shape and uses its marker
extractor. Tests cover an RC cut that the verifier then accepts, the
refused prerelease shapes, and the triple/RC boundary. The release guide
documents the RC cut and the Release-As footer later candidates need.
@github-actions github-actions Bot added the type:bug Something isn't working label Sep 26, 2026
A dry-run cut of the 1.0.0-rc.1 release PR failed four pre-commit gates on
the cut commit itself:

- The archived changelog index ended CHANGELOG.md with a blank line when no
  older release section exists, which end-of-file-fixer rejects.
- check-issue-reference-provenance.py and test_research_digest_ids.py read
  changelog fragments the cut deletes. The provenance checker now follows
  consumed fragments and CHANGELOG.md prose into the released changelog once
  a cut receipt exists; a missing fragment without a receipt still fails.
  The research-digest test reuses that resolver and checks the legacy link
  target rather than every mention of the old file name.
- Retired ADR-0864 listed a fragment as evidence; its two ADRs remain.

With these, pre-commit and verify-release-version.sh pass on the dry-run cut.
@lusoris
lusoris merged commit e0e1385 into master Sep 26, 2026
110 checks passed
@lusoris
lusoris deleted the fix/release-rollover-rc-versions branch September 26, 2026 23:19
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

type:bug Something isn't working

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant