How the generator sorts your lines
Each line becomes one item. The generator only sorts lines that say where they belong, using formats developers already write. It never guesses from the wording.
- feat: goes to New, fix: to Fixed, and perf: or refactor: to Improved. These are Conventional Commits prefixes. A scope in brackets, like feat(reports):, becomes a label on the item.
- A ! after the type, as in feat!:, or a line starting with BREAKING CHANGE:, goes to Breaking changes.
- docs:, test:, build:, ci:, style:, and chore: go to Maintenance, which is left out unless you include it. Git merge lines go there too.
- Section labels work as a prefix, like Fixed: at the start of a line, or as a heading line above a group, like ## Fixed. New, Added, Improved, Changed, Fixed, Security, Removed, and Breaking changes are recognized.
- Anything else lands in Other, where you pick a group for each line or leave it out.
Bullets, numbering, and the short hashes from git log --oneline are removed, and each item starts with a capital letter.
Writing release notes people read
Release notes are for the people who use your product, not for the team that built it. A few habits keep them useful:
- Lead with what someone can do now. "Export any report to CSV" says more than "Added CSV export endpoint".
- Keep one change per line, so each item can be scanned on its own.
- Put breaking changes first and say what people need to do about them.
- Leave internal work out. Refactors and dependency bumps matter to your team, not to most readers.
- Link to the docs for anything that needs more than a sentence.
Where to publish them
Markdown works in GitHub releases, a CHANGELOG.md file, and most docs tools. The HTML snippet pastes into a CMS or an email. To reach people while they use your product, publish the notes inside it.
Last reviewed