Skip to content

release: list one line per change in the GitHub release notes - #153

Merged
allen0099 merged 1 commit into
masterfrom
release/short-release-notes
Sep 25, 2026
Merged

allen0099 merged 1 commit into
masterfrom
release/short-release-notes

Conversation

@allen0099

Copy link
Copy Markdown
Owner

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:

- **Add `CacheManager.add()` for store-if-absent writes.** Details as before... ([#65](...))

scripts/changelog_release.py gets a new release_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:

### Changed

- GitHub release notes list one line per change.

**Full changelog**: https://fastapi-cachex.readthedocs.io/en/stable/changelog/#038-2026-09-26

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:

  • the release job (and a dry_run) stops before it publishes anything;
  • test_real_changelog_promotes, which promotes the real CHANGELOG.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.md and docs/CONTRIBUTING.md explain 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.py at 100% coverage. The new tests cover:
    • multi-line summaries;
    • nested lists;
    • several links in one entry;
    • entries before any heading;
    • listing every entry that lacks a summary;
    • rejecting lines that are not entries;
    • main writing nothing when it refuses.
  • Full suite against live Redis and Memcached: 766 passed, 100% total coverage.
  • Rehearsal on a copy: promoted the real changelog and ran zensical build --strict (no issues). The #038-2026-09-26 anchor that the release notes link to exists in the built changelog page.

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.
@allen0099
allen0099 merged commit 0494011 into master Sep 25, 2026
11 checks passed
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.
@allen0099
allen0099 deleted the release/short-release-notes branch September 26, 2026 11:49
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