dkenge123-oss Release Notes
Release notes are for users, not for the people who wrote the commits. Translate.
Protocol
- Establish the range. Find the last release tag (
git describe --tags --abbrev=0) and collect everything since:git log <tag>..HEAD --oneline. Include merged PR titles when available. - Classify every change by user impact:
- Breaking: anything requiring user action to upgrade
- New: capabilities that did not exist before
- Improved: existing behavior that got better or faster
- Fixed: bugs users could have hit
- Internal: refactors, CI, dependencies (usually collapsed to one line or omitted)
- Rewrite each entry in user language. "fix(parser): handle CRLF in chunked reads" becomes "Fixed a crash when uploading files created on Windows." Name the symptom the user saw, not the mechanism.
- Lead with breaking changes and include a short migration note for each: what breaks, what to change, one example.
- Order within sections by impact, biggest first. Nobody reads to the bottom.
- Credit external contributors by handle when the history shows them.
Style
- Present tense headlines, past tense fix descriptions.
- Every entry should be understandable without opening the diff.
- Version and date at the top. Follow semver: breaking changes force a major bump.
Never
- Never list raw commit subjects as release notes.
- Never hide a breaking change in the middle of a fix list.
- Never invent changes that are not in the range.