docs: keep a changelog, and put it above the generated release notes - #677
Merged
Conversation
A release body is git-cliff over the commit subjects, which answers which pull requests went in. The consumers - the apps, the bindings, and the packages on conan, maven, PyPI, npm and SwiftPM - ask a different question before taking a bump: does the API break, what renders better, what changed under them. Droid already narrates our changes for its own users by reading that commit list; this is that work done once, at the source. CHANGELOG.md is backfilled to v5.3.0, high level but written for a developer: `File::from_memory` and `HtmlViewportMode` are named where naming them is the point, and the PDF renderer is four bullets rather than sixty pull requests. `release.py notes` now writes the section for the version, a rule, then the generated list as before, and `release.py changelog` prints one section and fails when there is none - checked in the `version` job, so release copy nobody wrote costs seconds rather than the apple build. `docs(changelog)` joins `chore(release)` in cliff.toml's skip list: the heading cut is a version number moving and would otherwise narrate itself in its own release. AGENTS.md carries the flow, and records that the next version cannot be derived from main - since the release train the tags sit on `chore(release)` commits only `releases` has, so main's nearest tag is v6.1.0 and drifting. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01VFcWjZhdxeWLE5Abg4qUex
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.
🤖 Generated with Claude Code
A release body is git-cliff over the commit subjects — accurate, free, and an
answer to "which pull requests went in", which is not the question a consumer
asks. The consumers are the apps, the bindings and the packages on conan, maven,
PyPI, npm and SwiftPM, and before taking a bump they want to know whether the
API breaks, what renders better, and what changed under them. Droid's changelog
already re-narrates our changes for its own users, written by reading our commit
list; this does that work once, here.
The file
CHANGELOG.md, backfilled to v5.3.0 and covering what is on main asUnreleased. High level, but written for a developer rather than for an appstore:
File::from_memoryandHtmlViewportModeare named where naming them isthe point, while the PDF renderer is four bullets instead of sixty pull
requests. Sources were the commit subjects, the diffs where a subject was
ambiguous, and the changelog draft that was written and then dropped from #627,
which is where the v6.0.0 breaking list comes from.
The file's own arrival is not an entry in it — by its own rule, only what a
consumer notices earns one.
The wiring
release.py noteswrites the section for the version, a rule, then thegenerated list exactly as before.
release.py changelog --versionprints one section and fails when it ismissing or empty.
release.ymlcalls it in theversionjob, so release copynobody wrote costs seconds instead of the apple build. Dry runs included —
a dry run is the rehearsal for the body.
docs(changelog)joinschore(release)incliff.toml's skip list: theheading cut is a version number moving, and would otherwise narrate itself in
its own release notes.
Verified end to end against a real
git-cliff 2.13.1: section on top, rule,generated groups below; and the missing-section path fails before git-cliff is
reached.
The flow
Entries land under
## Unreleasedin the pull request that makes the change.The heading is cut to the version as the last commit on main before the merge
into
releases, so both branches carry the identical cut and the merge staysclean. AGENTS.md gains that, the amended wording of "main carries no version",
and a maintenance-branch rule: such a branch keeps its own changelog, covering
what it contains, and does not send sections back to main.
It also records a wart this PR does not fix: the next version cannot be
derived from main. Since the release train, tags sit on
chore(release)commits that only
releasescarries, sogit describe mainsaysv6.1.0-38-g890c5e6candscripts/release.py versionwould answer with analready-tagged version. Until that changes, take the last release from
gh release list -L 1and bump the minor if afeat:landed, the patch otherwise —and if the guess is wrong, the new check refuses in the first job.
Separately discussed and deliberately not in this PR: dropping the
releasesbranch and letting the release run cut the heading itself, whichremoves both the manual step and the wart above.