Repository navigation
ci(release): link the changelog from release notes instead of inlining it - #369
Merged
Merged
Conversation
DeepDiver1975
marked this pull request as draft
September 16, 2026 20:46
…g it The release body is German for the ELW crews who download the packages, while CHANGELOG.md is written in English. #364 inlined the English section into that German body; link to it instead, so the notes read as one language and the detail stays one click away. The link points at CHANGELOG.md at the release tag rather than at a heading anchor: GitHub's slug for '## [0.6.0] - 2026-09-16' embeds the release date and would rot silently. At its own tag the version's section is the top one in the file in any case. Also fail a tag that has no changelog section. Extraction used to fall back to a placeholder and publish the release notes-less, and that becomes easier to hit once the release section is assembled deliberately rather than accumulating on its own. The check runs in the `version` job — the only one that runs before the Windows (2x) and Android builds — so a forgotten release section costs seconds rather than build minutes. The placeholder fallback is gone with the step that produced it; the guard replaces it. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Signed-off-by: Thomas Müller <1005065+DeepDiver1975@users.noreply.github.com>
The guard demanded a section matching the tag exactly, so `v0.6.0-beta.1` required `## [0.6.0-beta.1]`. A prerelease is cut from work in progress, before that version's section is assembled, so no such heading exists and the guard blocked exactly the beta tagging #364 added. Caught by running the workflow end to end in a throwaway repository: the `v0.5.0-rc.1` tag failed in the `version` job with "No CHANGELOG.md section for v0.5.0-rc.1" and published nothing. Final releases still require their section. The body links to CHANGELOG.md rather than inlining it, so a beta without one still reads correctly. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Signed-off-by: Thomas Müller <1005065+DeepDiver1975@users.noreply.github.com>
DeepDiver1975
force-pushed
the
ci/release-notes-link
branch
from
September 20, 2026 20:50
2b3cadd to
723a92e
Compare
DeepDiver1975
marked this pull request as ready for review
September 20, 2026 20:50
DeepDiver1975
added a commit
that referenced
this pull request
Sep 20, 2026
The release runbook still told the maintainer to "move the [Unreleased] entries under a new version heading before tagging" — the one step this branch removes. Following it after this merges produces no section at all, and with the guard from #369 in place the tag is refused outright. Replace that with the towncrier build, keeping the three things it does not do for you: the summary paragraph, the link definitions at the bottom of CHANGELOG.md, and the milestone. The tag command moves below the assembly, which is the order it now has to happen in. CONTRIBUTING.md's Hacktoberfest bullet still listed "a CHANGELOG.md entry" among the unchanged rules, contradicting the section below it that says never to edit that file; and its "Cutting a release" section now duplicated the runbook, so it points at docs/releasing.md instead of maintaining the same steps twice. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Signed-off-by: Thomas Müller <1005065+DeepDiver1975@users.noreply.github.com>
DeepDiver1975
added a commit
that referenced
this pull request
Sep 20, 2026
* build(changelog): assemble CHANGELOG.md from per-PR fragments Every pull request inserted its bullet at the top of the same list under `## [Unreleased]`, so the insertion anchor was byte-identical across branches. Git saw two independent inserts at one position, could not order them, and conflicted — and merging any one PR invalidated every other open PR's hunk. `git merge-tree` reproduces it: #334 and #335 conflicted on CHANGELOG.md and nothing else, while two PRs writing to different sections merged clean. Each change now carries its entry as its own file in changelog.d/, which towncrier folds into CHANGELOG.md when a release is cut. Different PRs create different files, so there are no shared lines left to conflict over. Fragments use towncrier's orphan naming (+<slug>.<type>.md) rather than the default <issue>.<type>.md: several entries cite the same ticket (#302), and issue-numbered filenames would have reintroduced the same collision as an add/add conflict. A `merge=union` driver in .gitattributes was tried first and rejected. It does resolve these merges correctly on the client, but GitHub does not run merge drivers server-side when computing pull request mergeability, so the PRs would still have shown as conflicting. The changelog-check job now runs `towncrier check` instead of requiring a CHANGELOG.md edit. Its job id and display name are unchanged, so an existing required status check keeps matching. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Signed-off-by: Thomas Müller <1005065+DeepDiver1975@users.noreply.github.com> * docs(releasing): fold the changelog with towncrier, not by hand The release runbook still told the maintainer to "move the [Unreleased] entries under a new version heading before tagging" — the one step this branch removes. Following it after this merges produces no section at all, and with the guard from #369 in place the tag is refused outright. Replace that with the towncrier build, keeping the three things it does not do for you: the summary paragraph, the link definitions at the bottom of CHANGELOG.md, and the milestone. The tag command moves below the assembly, which is the order it now has to happen in. CONTRIBUTING.md's Hacktoberfest bullet still listed "a CHANGELOG.md entry" among the unchanged rules, contradicting the section below it that says never to edit that file; and its "Cutting a release" section now duplicated the runbook, so it points at docs/releasing.md instead of maintaining the same steps twice. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Signed-off-by: Thomas Müller <1005065+DeepDiver1975@users.noreply.github.com> --------- Signed-off-by: Thomas Müller <1005065+DeepDiver1975@users.noreply.github.com> Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
This was referenced Sep 21, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
The GitHub Release body is German — it is read by the ELW crews who download the packages —
while
CHANGELOG.mdis written in English. #364 wired the changelog into the release notesby inlining the English section into that German body. This keeps the wiring but makes
it a link, so the notes read as one language and the detail is one click away.
This partially reverts #364: the
Extract changelog sectionstep goes away, and therelease body gains one line in its place.
The link targets
CHANGELOG.mdat the release tag, with no#anchor. GitHub's slug for## [0.6.0] - 2026-09-16embeds the release date, so an anchor would rot silently — and atits own tag that version's section is the top one in the file anyway.
Fail fast on a missing changelog section
Extraction previously fell back to
_No changelog entry found for v${VERSION}…_andpublished the release anyway. That failure gets easier to hit once the release section is
assembled deliberately instead of accumulating on its own (see #354), and it happened in
the
releasejob — after Windows (2× billing) and Android minutes were already spent.The check now runs in the
versionjob, the only one that runs before any build:Guarded to
push, so the macOSworkflow_dispatchpath — which runs against a branchrather than a tag — is unaffected. The placeholder fallback disappears along with the step
that produced it; this guard replaces it, and fails loudly instead of quietly.
Verification — run end to end
Exercised against real GitHub Actions runs and real GitHub Releases in a private throwaway
repo (
versionandreleasejobs copied verbatim; the three build jobs stubbed to emitdummy artifacts under the real filenames). Nothing was tagged or released here.
v0.5.0isPrerelease: false, all three assets attached, body entirely German with the link — no English changelog textv9.9.9versionfailed, all build jobs skipped, no release createdv0.5.0-rc.1versionfailed — the prerelease bug, see belowv0.5.0-rc.2(after the fix)isPrerelease: true,> **Vorabversion.**blockquote leads, assets attachedThe guard's annotation renders as intended:
Also run against the fragment scheme from #354
The runs above used today's
CHANGELOG.md. Since #354 changes what that file looks like ona release day, the two were then composed in the same fixture —
towncrier.toml,changelog.d/and the restructuredCHANGELOG.mdalongside this workflow:v0.7.0, fragments not builtversionfailed, builds skipped, no release — the guard catches a forgottentowncrier build, which is the failure mode #354 makes possiblev0.7.0-beta.1, fragments not builtisPrerelease: true— betas need no section, as intendedv0.6.0, aftertowncrier buildCHANGELOG.mdat the tag carries## [0.6.0] - 2026-09-17with all 20 entries,changelog.d/empty,## [Unreleased]pointer intactThe last row is the one that matters for the link in the body: it confirms the file a reader
lands on actually contains that version's entries.
The test caught a bug in this PR
The guard originally required a section matching the tag exactly, so
v0.6.0-beta.1needed## [0.6.0-beta.1]. A prerelease is cut before that section is assembled, so every betatag would have been blocked — breaking exactly the tagging #364 added.
v0.5.0-rc.1failed and published nothing, which is how it was found. Fixed in 2b3cadd: the guard is now
skipped when
prerelease == 'true'; final releases still require their section.Notes
src/changes, and this isCI-only — but more to the point, adding a bullet to
## [Unreleased]would conflict withbuild(changelog): assemble CHANGELOG.md from per-PR fragments #354, which is exactly the problem that PR exists to remove.
section exists, which is true before and after the towncrier switch.
🤖 Generated with Claude Code