Skip to content

ci(release): link the changelog from release notes instead of inlining it - #369

Merged
DeepDiver1975 merged 2 commits into
mainfrom
ci/release-notes-link
Sep 20, 2026
Merged

DeepDiver1975 merged 2 commits into
mainfrom
ci/release-notes-link

Conversation

@DeepDiver1975

@DeepDiver1975 DeepDiver1975 commented Sep 16, 2026 •

Copy link
Copy Markdown
Contributor

Why

The GitHub Release body is German — it is read by the ELW crews who download the packages —
while CHANGELOG.md is written in English. #364 wired the changelog into the release notes
by 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 section step goes away, and the
release body gains one line in its place.

> **Vorabversion.** …                    ← unchanged (prerelease tags only)

→ [Alle Änderungen in dieser Version](…/blob/v0.6.0/CHANGELOG.md)     ← replaces the
                                                                        inlined English
Getaggter Release-Build.                 ← unchanged from here down

| Plattform | Datei |
…
**Die Pakete sind nicht signiert.** …

The link targets CHANGELOG.md at the release tag, with no #anchor. GitHub's slug for
## [0.6.0] - 2026-09-16 embeds the release date, so an anchor would rot silently — and at
its 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}…_ and
published 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 release job — after Windows (2× billing) and Android minutes were already spent.

The check now runs in the version job, the only one that runs before any build:

::error::No CHANGELOG.md section for v9.9.9 — assemble the release section before tagging.

Guarded to push, so the macOS workflow_dispatch path — which runs against a branch
rather 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 (version and release jobs copied verbatim; the three build jobs stubbed to emit
dummy artifacts under the real filenames). Nothing was tagged or released here.

Tag Result
v0.5.0 release created, isPrerelease: false, all three assets attached, body entirely German with the link — no English changelog text
v9.9.9 version failed, all build jobs skipped, no release created
v0.5.0-rc.1 version failed — the prerelease bug, see below
v0.5.0-rc.2 (after the fix) release created, isPrerelease: true, > **Vorabversion.** blockquote leads, assets attached

The guard's annotation renders as intended:

No CHANGELOG.md section for v9.9.9 — assemble the release section before tagging.

Also run against the fragment scheme from #354

The runs above used today's CHANGELOG.md. Since #354 changes what that file looks like on
a release day, the two were then composed in the same fixture — towncrier.toml,
changelog.d/ and the restructured CHANGELOG.md alongside this workflow:

Tag Result
v0.7.0, fragments not built version failed, builds skipped, no release — the guard catches a forgotten towncrier build, which is the failure mode #354 makes possible
v0.7.0-beta.1, fragments not built release created, isPrerelease: true — betas need no section, as intended
v0.6.0, after towncrier build guard passed on towncrier's own heading; release created; CHANGELOG.md at the tag carries ## [0.6.0] - 2026-09-17 with all 20 entries, changelog.d/ empty, ## [Unreleased] pointer intact

The 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.1 needed
## [0.6.0-beta.1]. A prerelease is cut before that section is assembled, so every beta
tag would have been blocked
— breaking exactly the tagging #364 added. v0.5.0-rc.1
failed 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

🤖 Generated with Claude Code

DeepDiver1975 and others added 2 commits September 20, 2026 22:50
…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
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
DeepDiver1975 merged commit 9a03bc5 into main Sep 20, 2026
6 checks passed
@DeepDiver1975
DeepDiver1975 deleted the ci/release-notes-link branch September 20, 2026 21:00
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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant