| name | polish-notes |
| description | Polish raw GitHub release notes into user-impact-focused summaries. Use when preparing release notes for a new chunkah version. |
Polish release notes
Polish raw GitHub-generated release notes for chunkah.
Input
The user provides the version to release (e.g. v0.4.0 or 0.4.0) and
optionally a path to a file containing raw release notes. Strip any v prefix
to get the bare version (e.g. 0.4.0).
If no file path is provided, run just release generate-notes <bare-version>
to fetch raw notes from GitHub. Request to run in the host context if you get a
403.
The raw notes contain entries in this format:
* <PR title> by @<author> in <PR URL>
Process
- Use
gh release list --repo coreos/chunkah --limit 5 to fetch recent
release tags, then gh release view <tag> --repo coreos/chunkah to read
their release notes. Use these as a reference for how items were categorized
in past releases.
- For each PR entry, parse the PR number from its URL, then use
gh pr view <number> --repo coreos/chunkah --json body,commits to fetch the PR
description and commit messages. Fetch all PR details in parallel to
minimize latency.
- From the PR body and commit messages, determine the user-facing impact of
the change (e.g. performance improvement, bug fix, new feature).
- Write a brief summary emphasizing impact to users, not implementation
details. Keep it to 1-3 sentences.
- Categorize each item into one of the sections below, using the previous
release notes as a guide for consistency.
Output format
Group items under these section headings (omit sections with no items):
- Major changes - New features, significant behavior changes, performance
improvements, or breaking changes that users should know about.
- Minor changes - Small enhancements, new options, improved warnings, or
documentation updates that are user-visible.
- Internal changes - Refactoring, CI fixes, test improvements, or code
cleanup with no direct user-facing impact.
- Packaging changes - Dependency bumps, spec file changes, Packit fixes, or
build system updates.
Rewrite each entry as:
* <user-impact summary> (<PR URL>)
If the raw notes contain a "## New Contributors" section, preserve it verbatim
at the bottom of the output, after all other sections.
Example
Input:
* tar: stream file reads instead of buffering into `Vec<u8>` by @jlebon in
https://github.com/coreos/chunkah/pull/72
Output:
## Major changes
* Dramatically reduced memory usage by streaming file reads instead of
buffering entire files and tar layers into memory, cutting peak RSS to ~75 MB
(from ~6.5 GB of allocations for an FCOS image)
(https://github.com/coreos/chunkah/pull/72)
Final steps
After drafting the output, check for spelling and grammar issues and fix them.
Write the final result to .release-notes-<bare-version>.md in the repo root
(e.g. .release-notes-0.4.0.md).
