Developer workflow guides

Review Conventional Commits before drafting release notes

·

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.

Changelog Entry Generator

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.

The breaking migration entry in the initial export
### 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.

Conventional Commits 1.0.0 specification

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.

Sources

Put it into practice.

Related guides