Release notes from per-PR changelog.d fragments#5685
Merged
norman-abramovitz merged 5 commits intoJul 23, 2026
Merged
Conversation
Per-PR fragment files changelog.d/NNNN-<slug>.md carry release-note entries under [Breaking Changes]/[Features]/[BugFixes]/[Chores]/ [Security Updates] headers. build/release-notes.sh provides new (next-sequence fragment), assemble (header-grouped concatenation in layout order), and sweep (git rm after a release consumes them). Fragments are transient — they ride each PR and live one release cycle.
stamp tag now embeds the assembled changelog.d fragments in the annotated tag body (pointer-line fallback when none exist); publish consumes it with --notes-from-tag unless NOTES=<file> overrides. The CHANGELOG.md extraction is superseded — the tag is the notes carrier. New plain verb 'make sweep' removes consumed fragments post-publish. Includes this change's own fragment.
actions/checkout resolves the tag ref to its commit, dropping the annotation whose body now carries the release notes. Fetch the real tag object so --notes-from-tag sees them; also covers workflow_dispatch runs where the tag was never checked out.
norman-abramovitz
approved these changes
Jul 23, 2026
norman-abramovitz
left a comment
norman-abramovitz
left a comment
Contributor
There was a problem hiding this comment.
LGTM - Minor issues that can be adjusted with follow on PRs
- Tag needs to be created at the beginning of the development cycle
This might mean draft PRs are created first or adding a make slug. - Redo the stamp vocabulary so the make steps is readable
- Add an optional review release notes make vocabulary.
- Resolve version number collisions when PRs are done out of order.
This might mean the version number - slug conversion is part of the final review process.
There is still a sequencing order issue but the window is smaller.
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
2 participants
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.
Follow-on to #5684. Release notes now accumulate continuously as per-PR fragment files instead of being written at release time.
How it works
changelog.d/NNNN-<slug>.md(./build/release-notes.sh newpicks the next sequence number and slugs the branch name). The fragment body uses the release-notes section headers directly —[Breaking Changes]/[Features]/[BugFixes]/[Chores]/[Security Updates]— so one file can feed multiple sections.make stamp tagassembles the fragments (header-grouped, sections in layout order, only populated sections;[Breaking Changes]leads when present) and embeds the result in the annotated tag body. With no fragments the tag body falls back to a pointer line.make publishuses the tag body as the GitHub release notes (--notes-from-tag);NOTES=<file>still overrides. The previous CHANGELOG.md section extraction is superseded — the tag is the notes carrier.make sweep(new plain verb) removes the consumed fragments after publishing; the removal commit rides the next PR. The directory is empty right after every release — fragments live one cycle.Concurrent PRs picking the same NNNN are harmless: the slug keeps filenames distinct, ties sort alphabetically. Unknown section headers fail assembly loudly.
release.yml
One added step before
make publish: re-fetch the tag object. actions/checkout resolves the tag ref to its commit, which silently drops the annotation that now carries the notes; the fetch also coversworkflow_dispatchruns where the tag was never checked out.Verification
build/test-release-notes.sh: numbering, slug sanitizing, header-grouped assembly order, populated-sections-only, unknown-section and stray-content failures (7/7).assemble→ annotated tag body →make publish DRYRUN=yesshows--notes-from-tag(and--notes-filewhenNOTES=is set);make sweep DRYRUN=yesclean.make check gategreen; zizmor clean on release.yml.This PR carries its own fragment as the first real entry, and bumps to v5.0.0-dev.144.