0xrsydn
809966925e
Release notes were written by hand on GitHub at tag time, so the contents of a stacked release had to be pieced together from every PR, and output changes that scripts and agents rely on were easy to miss. - CHANGELOG.md backfills every published release (0.2.0 to 0.4.0) from its GitHub notes, verbatim. - A PR adds changes/unreleased/<branch-name>.md instead of editing CHANGELOG.md, so stacked PRs never conflict. changes/README.md gives the sections, including Output Changes for JSON, MCP and error-code changes. - scripts/changelog.sh: `check` validates entries and CHANGELOG.md, `release X.Y.Z` folds the entries into a new section (ordered by PR), and `notes X.Y.Z` prints a section as GitHub release notes. - The release workflow sets the GitHub notes from the tag's section. - New flake check `changelog` runs scripts/changelog-test.sh; both scripts are shellchecked. - Entries for 0.5.0: #73, #74, #75, #78, #79, #80, #81 and this PR. Claude-Session: https://claude.ai/code/session_01RqPPVeVDrnLoP7NUZmLRxY
1.8 KiB
Changelog entries
Every pull request that changes what users or agents see adds one file here,
changes/unreleased/<branch-name>.md; for example, fix/mcp-warnings adds
changes/unreleased/mcp-warnings.md. Each PR has its own file, so stacked PRs
never conflict over the changelog. Internal refactors, CI-only and test-only
changes need no entry.
An entry holds ### <section> headings with one bullet per change. Write each
bullet as one sentence for the user, saying what changed for them, and end it
with the PR number:
### Bug Fixes
- `ownership import` reads IDX's register from October 2026 on, which adds a `CONTROLLER_OR_AFFILIATE` column. (#79)
The sections, in the order a release lists them:
| Section | For |
|---|---|
Security |
vulnerabilities, with what an attacker could do |
New Features |
new commands, tools, flags and providers |
Bug Fixes |
wrong output, crashes, failures |
Improvements |
speed, robustness, help text, distribution |
Output Changes |
any change to JSON fields, MCP results, error codes or exit codes that scripts and agents read; start a breaking one with Breaking: |
Docs |
user-facing documentation |
Testing |
what was verified, when a release needs to say so |
Notes |
dependencies, requirements, known limits |
A release may add changes/unreleased/summary.md: a short paragraph with no
headings that opens its notes, such as "Upgrade from 0.3.2: ...".
scripts/changelog.sh check (part of nix flake check) validates the entries.
At release time, scripts/changelog.sh release X.Y.Z folds them into a new
section of CHANGELOG.md and deletes them; edit the section
if needed and commit it with the version bump. The release workflow publishes
that section as the GitHub release notes.