Carry the reason for a release from the pull request that made it

[JDS300]

Stacked on #18 — its diff shows only this change, and GitHub will retarget it to main when #18 merges.

Generated notes list what changed. They cannot say what any of it was for. That part was hand-written onto the release page after the fact, which lasts exactly as long as someone keeps doing it — and is reconstructed from a diff rather than remembered.

How it works

CHANGELOG.md holds one entry per version, written in the pull request that makes the change:

## 0.4.0

First build carrying the upstream work merged since 0.3.4 ...

### Fork-specific
- **Every raid kill awaiting a difficulty is kept.** ...

A candidate and the release it is promoted to resolve to the same entry: 0.4.0-rc.1, 0.4.0-rc.2 and 0.4.0 all read ## 0.4.0. So the explanation written once is carried by every build that ships it, with nothing re-typed into a release page.

The published release then reads: the entry, then install instructions naming the real artifacts, then the pull requests merged since the last full release.

Failing early

Publishing a version with no entry fails in detect-changes — seconds in — rather than at the publish step twenty minutes of building later:

- name: Require a changelog entry for the release being published
  if: github.event_name == 'workflow_dispatch' && inputs.publish_release
  run: python tools/release_notes.py --version '${{ inputs.release_tag }}' --check

Why a script rather than text handling in the workflow

tools/release_notes.py carries its own self-test, which the release gate runs. The behaviours worth asserting are exactly the ones that are awkward to eyeball inside PowerShell: a candidate reading its release's entry, an entry running to the end of the file, the next entry not leaking into this one, and a missing entry being reported rather than guessed at.

Verification

• release notes extractor: ALL PASS, wired into the release quality gate
• Extraction checked against the real CHANGELOG.md for v0.4.0-rc.1, and a missing version exits 1 with an actionable message
• Full notes rendered end to end for v0.4.0: entry, install steps, generated changelog
• Release quality gate ALL PASS under TZ=UTC; workflow parses
• CHANGELOG.md added to the trigger paths, since it decides what a release says

CHANGELOG.md is seeded with the 0.4.0 entry, so promoting v0.4.0-rc.1 will carry the same explanation the candidate's notes now have — without anyone editing a release page.

🤖 Generated with Claude Code