Review Conventional Commits before drafting release notes
Admin ·
Start with saved commit messages and decide which changes matter to people using your project. A Conventional Commit type suggests a heading. A breaking marker tells you to keep the compatibility information, including the migration steps in a footer.
Review the five saved messages
Select Load example, then Review commits. Full commit messages uses a standalone line of three hyphens between messages. The sample contains a feature, a fix, a breaking refactor, a chore and an unmatched subject.
Three of the five messages start selected. Saved filters appear under Added and the CSV fix appears under Fixed. The API change opens the Breaking changes group, with the subject and the migration note about /v2/status.
### Breaking changes
- api — remove the legacy status endpoint
- Replace /status with /v2/status. Update clients before deploying.Conventional Commits 1.0.0 specificationKeep a Changelog 1.1.0 guiding principles
Keep the migration note from the footer
In the example, remove the exclamation mark just before the refactor subject's colon and review again. The uppercase BREAKING CHANGE footer still makes it a breaking entry. Its two description lines stay together. The following Refs footer stays outside the migration note.
If you only have subjects, select One subject per line. The exclamation mark before a subject's colon still identifies a breaking change. Paste complete messages whenever release readers need the footer's instructions.
Include an unmatched subject after choosing its category
For Message 5, set Category to Changed and select Include. The first-run instructions now appear under Changed, with four of the five messages selected. Leave the local development-cache chore unchecked.
Download changelog-entries.md and open it in your Markdown reader. Confirm the breaking subject and migration instruction are both present. Edit the exported wording where several commits describe the same feature or where readers need more context.
Keep a Changelog 1.1.0 guiding principlesConventional Commits 1.0.0 specification
Common questions
Does the exclamation mark have to come after the scope?
It goes immediately before the colon, as in feat!: or feat(api)!:. An uppercase breaking footer can identify the change independently.
Can I paste just the migration text?
Include the commit subject with it. The exported breaking entry uses the subject to identify the change and the footer to explain what readers need to do.