release: list one line per change in the GitHub release notes - #153
Merged
Merged
Conversation
The release body used to be the promoted changelog section verbatim. Our entries explain each change in full, so the 0.3.7 release page was about 8 KB of long bullets. GitHub also renders every hard wrap as a line break, which made them longer still. Each changelog entry now opens with a bold one-line summary. The new release_notes() in scripts/changelog_release.py turns the promoted section into those summaries plus the issue links found in each entry, grouped under the same ### headings. It ends with a link to the version's section on the documentation site's changelog, which keeps the full entries. An entry without a summary, or a line that is neither a ### heading nor a list entry, is an error that names the entries. The release therefore stops before publishing anything, and so does a dry run. The test that promotes the real CHANGELOG.md runs the same check, so the pull request that adds an entry without a summary fails CI instead of the release. CHANGELOG.md, DEVELOPMENT.md and CONTRIBUTING.md describe the format. Released versions are left as they are.
This was referenced Sep 25, 2026
allen0099
added a commit
that referenced
this pull request
Sep 25, 2026
The pull_request triggers of these four workflows had the same paths filter as their push triggers (Python files, pyproject.toml and the workflow itself). That caused two problems. A pull request that changes only CHANGELOG.md never ran the tests, so the changelog format check added in #153 (test_the_repository_changelog_can_be_released) did not run on it. A changelog entry without a bold summary would only have failed at release time. The same applied to pull requests that change only uv.lock or tox.ini. These checks also could not be made required before merging. A required check whose workflow is filtered out never reports, so the pull request would wait for it forever. The pull_request triggers now have no paths filter. The push triggers keep theirs, since master has already been checked through its pull requests. The slowest check is tox, at about four minutes.
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 GitHub release body used to be the promoted changelog section, copied as is. Our entries explain each change in full, so the v0.3.7 release page was about 8 KB of long bullets. GitHub also turns every hard wrap into a line break, which makes the bullets even longer.
What changes
Each changelog entry now opens with a bold one-line summary:
scripts/changelog_release.pygets a newrelease_notes(). It writes the release body as one line per entry: the summary plus the issue/PR links found in that entry, grouped under the same###headings. The body ends with a link to that version's section in the changelog on the documentation site:The workflow still adds the Installation block and the "Full commit log" compare link below this, as before.
Gate
An entry without a bold summary, or a line that is neither a
###heading nor a-entry, is an error. The error message lists the offending entries. This means:dry_run) stops before it publishes anything;test_real_changelog_promotes, which promotes the realCHANGELOG.md, runs the same check. A pull request that adds an entry without a summary therefore fails CI, not the release.CHANGELOG.md,docs/DEVELOPMENT.mdanddocs/CONTRIBUTING.mdexplain the format. Releases already published, and changelog entries before 0.3.8, stay as they are.Verification
tests/test_changelog_release.py: 25 passed,scripts/changelog_release.pyat 100% coverage. The new tests cover:mainwriting nothing when it refuses.zensical build --strict(no issues). The#038-2026-09-26anchor that the release notes link to exists in the built changelog page.