polish-notes

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

1. 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.
2. 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.
3. From the PR body and commit messages, determine the user-facing impact of the change (e.g. performance improvement, bug fix, new feature).
4. Write a brief summary emphasizing impact to users, not implementation details. Keep it to 1-3 sentences.
5. 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).