Guide
Writing Conventional Commits and working out the next version
Conventional Commits is a small convention for commit messages that makes history readable for people and machines. Release tools such as semantic-release, release-please and changesets read it to decide the next version number and to write changelogs. This builder writes messages in the format, checks the style rules most teams use, and shows which version the change would release.
The structure
A message has a header, an optional body and optional footers, separated by blank lines. The header is type(scope): description, where the scope is optional and names the part of the code, such as api or checkout. An exclamation mark before the colon marks a breaking change. The body explains what changed and why, wrapped at 72 characters so it reads well in terminals. Footers hold structured information such as BREAKING CHANGE: notes, issue references and co-authors.
Types and what they release
feat is a new feature and releases a minor version. fix is a bug fix and perf a performance improvement, both patch releases, as is revert. docs, style, refactor, test, build, ci and chore describe changes that do not affect users directly and release nothing on their own. A breaking change of any type releases a new major version.
Breaking changes
There are two ways to mark one, and the builder uses both when you tick the option: the ! in the header, which shows up in one-line logs, and a BREAKING CHANGE: footer that explains what users must change. The footer is what changelog generators quote, so describe the migration, not just the fact.
The style checks
The builder warns when the header is longer than 72 characters, because git log, GitHub and many tools cut it off; 50 is a good target. It suggests starting the description in lower case and leaving out the final full stop, by convention. It also flags descriptions that start with “added”, “fixed” or “updates” and suggests the imperative mood, as if completing the sentence “If applied, this commit will …”.
From commit to version
Semantic Versioning 2.0 numbers releases as MAJOR.MINOR.PATCH. Enter the current version and the builder shows the next one for this commit: a feat on 1.4.2 releases 1.5.0, a fix 1.4.3, and a breaking change 2.0.0. While a project is still below 1.0.0, breaking changes bump the minor version instead, as most release tools do, because 0.x versions promise no stability.
A worked example
The Sample is a breaking feature in the auth scope. Its header is feat(auth)!: require email verification before first login, followed by a two-line body, a footer BREAKING CHANGE: the /login endpoint now returns 403 with code "email_unverified" for unverified accounts. and Closes #482. From version 1.4.2 the next version is 2.0.0, and the shell line repeats the message as a git commit command with one -m per paragraph.
Making it stick
To enforce the format, add commitlint with the conventional preset and run it in a Git hook or in CI on pull request titles. Keep the list of scopes short and documented, and let the tooling write the changelog from the history.
Related tools
- Git Command Finder has recipes for amending and squashing commits.
- .gitignore Generator keeps noise out of the commits you write.
- package.json Analyzer checks the version field releases update.
- Diff Checker shows what a commit changes.
Checked against the current version of the Conventional Commit Builder on .