Repository navigation
docs(changelog): one entry per pull request - #434
Merged
Merged
Conversation
The changelog rule was never actually written down. AGENTS.md and CONTRIBUTING.md said "add a changelog entry as its own file", which does not say how many, and #431 arrived with seven fragments — one per commit, describing a single feature layer by layer, plus an unrelated build fix. State the rule in both places and in the PR template: exactly one entry per pull request, describing what the change does for the reader rather than the layers it was built in. A PR carrying an unrelated fix folds it into the same entry; if the two cannot share an entry they are two pull requests. Then make the existing fragments follow it. Seven merged pull requests had contributed more than one entry, 22 files between them, now 7 — #313, #310, #355, #390, #395, #411 and #431. The prose is rewritten rather than concatenated, but nothing a reader would act on is dropped: schema versions, migrated JSON keys, file-format compatibility, what changes on first open and what stays untouched all survive, as do the ticket references. The remaining 27 fragments were already one-per-PR and are untouched. `towncrier build --draft` renders 34 entries across Added, Changed, Fixed and Security. 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 23, 2026
…ry (#453) The language of an entry was predicted by the date its fragment was committed, not by who reads it: 32 English entries in [0.6.0], 9 German, 2 ambiguous, switching on 2026-09-21. release.yml already said in a comment that the changelog is English and the German release body is what ELW crews read, so the drift contradicted a decision the repository had already written down. The rule now says English and one sentence. Short matters as much as English does: the sediment formed because 300 words of careful prose at 23:00 after an exercise is not a thing that happens twice, and the cheap path won. The pull request holds the detail; the entry says what changed. Every bullet opens with a link to that pull request. Nobody can write it by hand — fragments are orphans (`+<slug>.<type>.md`, so two PRs citing one ticket cannot collide), so towncrier has no number, and the number does not exist while the PR is open. After a squash-merge exactly one commit adds a given fragment and its subject ends in `(#NNN)`, so scripts/changelog-prlinks.py recovers it just before `towncrier build`. It is idempotent, and it refuses to resolve a fragment it cannot place rather than cutting a release with an entry silently unlinked. The language check is advisory on purpose. Every correct entry here carries German Fachbegriffe — Atemschutz, Stammdaten, Messreihe — so a detector strict enough to gate on would fail hardest on the entries that are right. It matches German function words only, outside code spans and links, and needs two distinct hits: against the 43 fragments of the 0.6.0 cycle that flags exactly the 9 German ones and nothing else. [0.6.0] is relinked, translated and compressed. Its links are not mechanical: 25 of its 43 fragments were backfilled by #354 and #434, so git names the changelog-infrastructure PR rather than the change, and each one was matched by hand instead. [0.1.0] through [0.5.0] stay as published — they predate changelog.d/ entirely and are a record of what shipped. Refs #447 Signed-off-by: Thomas Müller <1005065+DeepDiver1975@users.noreply.github.com> Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
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 changelog rule was never written down.
AGENTS.mdandCONTRIBUTING.mdsaid only "add achangelog entry as its own file" — which does not say how many — so #431 arrived with seven
fragments: one per commit, describing a single feature layer by layer (domain → persistence →
Stammdaten → sidebar → editor → rail), plus an unrelated build-hygiene fix. That is not what a
release note should look like.
One entry per PR was already the de facto norm — 27 of 33 merged pull requests contributed exactly
one — but seven did not.
What this does
States the rule in
AGENTS.md,CONTRIBUTING.mdand the PR template: exactly one entry perpull request, describing what the change does for the reader rather than the layers it was built
in. A PR carrying an unrelated fix folds it into the same entry; if the two cannot share an entry,
they are two pull requests.
Makes the existing fragments follow it. 22 files become 7:
+checklisten-and-navigation.changed.md+trupp-typ-rules-in-stammdaten.fixed.md+uebersicht-scroll-and-glow.fixed.md+einsatzdaten-dialog.added.md+linux-desktop-entry.fixed.md+kraefte-status-and-funktionen.fixed.md+codeql-alerts-to-zero.changed.mdThe remaining 27 fragments were already one-per-PR and are untouched.
Cluster membership was derived by replaying
main'sCHANGELOG.mdhistory commit by commit(
v0.5.0..33dbe81~1) and attributing each[Unreleased]bullet to the commit that introduced it —not guessed from filenames.
What a reviewer should check
The prose is rewritten, not concatenated, so the thing worth reviewing is whether anything was
lost. The rule applied: no fact a reader would act on may be dropped — schema versions, migrated
JSON keys, file-format compatibility, what changes on first open, what stays untouched. Only the
layer-by-layer narration goes, because it existed solely because the commits did.
Checked mechanically, every load-bearing token survives, including
V23,checklistTemplateAufbau,the
checklists/navigationexport keys, ABBAU-Reiter,CSA Trupp/CSA-Trupp (Chemikalienschutz)/Chemietrupp,AGT/CSA/LPA,SignalFadedColor,StartupWMClass,hicolor-icon-theme,20260819-2217.fwincident, and the(#302),(#310),(#376),(#397),(#418)and(#337)references.towncrier build --draft --version 0.6.0exits 0 and renders 34 entries across Added, Changed,Fixed and Security.
Known consequence
"Exactly one" forces a single Keep a Changelog section per PR, so a pull request that both added and
fixed something loses that split in the release notes — #411's Strahlenschutztrupp example folds
into its Trupp-Typ fix, and #313's new Einsatzdaten dialog absorbs the new-incident dialog change.
#313's pair reads the least naturally of the seven. Worth a look before merging if that trade is not
the one you want.
Notes
and "one change" is an editorial judgement rather than an arithmetic one.
src/changes here, sotowncrier checkrequires no fragment for this PR itself.🤖 Generated with Claude Code