Skip to content

docs(changelog): one entry per pull request - #434

Merged
DeepDiver1975 merged 1 commit into
mainfrom
docs/changelog-one-entry-per-pr
Sep 20, 2026
Merged

DeepDiver1975 merged 1 commit into
mainfrom
docs/changelog-one-entry-per-pr

Conversation

@DeepDiver1975

Copy link
Copy Markdown
Contributor

Why

The changelog rule was never written down. AGENTS.md and CONTRIBUTING.md said only "add a
changelog 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.md and 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.

Makes the existing fragments follow it. 22 files become 7:

Pull request Fragments Becomes
#431 Checklisten und Navigation 7 +checklisten-and-navigation.changed.md
#411 Trupp-Typ rules in the Stammdaten 4 +trupp-typ-rules-in-stammdaten.fixed.md
#395 Übersicht reflow and corner glow 3 +uebersicht-scroll-and-glow.fixed.md
#313 Einsatzdaten dialog 2 +einsatzdaten-dialog.added.md
#310 Linux desktop entry and icon 2 +linux-desktop-entry.fixed.md
#355 Kräfte status and Funktionen 2 +kraefte-status-and-funktionen.fixed.md
#390 CodeQL alerts to zero 2 +codeql-alerts-to-zero.changed.md

The remaining 27 fragments were already one-per-PR and are untouched.

Cluster membership was derived by replaying main's CHANGELOG.md history 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/navigation export 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.0 exits 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

  • No CI enforcement. Counting files would fail a legitimate PR that also edits an existing fragment,
    and "one change" is an editorial judgement rather than an arithmetic one.
  • No src/ changes here, so towncrier check requires no fragment for this PR itself.

🤖 Generated with Claude Code

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
DeepDiver1975 merged commit 3ad3c4c into main Sep 20, 2026
6 checks passed
@DeepDiver1975
DeepDiver1975 deleted the docs/changelog-one-entry-per-pr branch September 20, 2026 21:30
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>
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