Release Notes Generation and Review Workflow
Generate user-facing notes from commit and PR history, classify entries by audience impact, and route them through a two-person review.
Objective
Produce release notes that a user can act on: what changed, why it matters, and what they must do, reviewed before publication.
Environment
- A release with merged PRs referencing issues
- A notes template with audience sections
- Reviewers from engineering and support
Steps
1. Harvest the change set
Collect all PRs merged between the previous tag and the candidate tag with titles, bodies, and linked issues.
Expected state: A complete list exists with no manual archaeology, including PRs missing labels.
2. Classify by audience impact
Sort entries into breaking changes, action required, new features, fixes, and internal-only, using PR labels plus a human pass.
Expected state: Every entry sits in one section, and internal noise is filtered out of user notes.
3. Write for the reader
Convert each entry from implementation language to user language: what they observe, what they gain, what they must do.
Expected state: Notes contain no internal jargon, ticket codes only as references, and explicit migration steps where required.
4. Review with support and engineering
Route the draft to one engineer who shipped the changes and one support member who will answer questions about them.
Expected state: Both approve, with support specifically confirming the action-required section is unambiguous.
5. Publish attached to the artifact
Attach the final notes to the release tag and artifact metadata so users find them next to the download.
Expected state: The release page and artifact metadata carry the identical notes text.
Expected outcome
Release notes that customers can follow without asking, with breaking changes and required actions surfaced at the top rather than buried.
Verification
A reader unfamiliar with the codebase can state what changed, whether action is required, and what that action is, after reading only the notes.
Cleanup
Archive the draft and review comments with the release for audit of what was communicated.
Notes are a product surface, not an archive dump
A git log pasted into a release page answers nobody’s question. Notes exist to tell users what changed for them and what they must do. Generating the raw list automatically and then shaping it for the reader gives both speed and clarity.
## 1.8.0 -- 2026-10-22
### Action required
- Config key `cache.ttl` is now seconds (was ms).
Multiply existing values by 1000 before upgrading.
### Breaking
- Removed `/v1/legacy-search` (deprecated since 1.4).
### Added
- Coupon engine: percentage and fixed codes at checkout.
### Fixed
- Checkout rounding on 3-decimal currencies.
### Internal
- (18 PRs omitted from user notes)Action required goes first
Users scan notes for one thing: do I need to do something? That section belongs at the top with concrete migration steps, not as a footnote after features. If the answer is no, say nothing required explicitly, which is itself valuable information.
The support reviewer is the quality bar
Engineering reviewers check accuracy; the support reviewer checks answerability, because they will personally answer tickets caused by unclear notes. Their approval criterion is simple: can I handle the questions this text will generate without escalating?