Conventional commits cheat sheet, on one screen

Definition

What this covers

Conventional Commits is a format for the first line of a commit message: a type, an optional scope in parentheses, a colon and a space, then a short description. You use it when you want a tool to pick the next version number and write the changelog from your git history. fix means a patch release, feat means a minor release, and a breaking change means a major one. The other types sort the changelog and carry no version meaning under the spec, which is at version 1.0.0. This sheet is the short form: the shape, the types, both ways to mark a breaking change, footers, what commitlint’s default config rejects, and ten commits you can copy. When a row needs explaining, like why semantic-release ignores feat! out of the box, the guide linked above has it.

Free tool

Check a commit

Paste a message or a few lines of git log --oneline. It runs in your browser against the spec and commitlint’s default rules.

Format

The header

<type>[optional scope][!]: <description>

[optional body]

[optional footer(s)]

• Colon, then exactly one space. feat:add x fails commitlint.
• Scope is optional. Empty parentheses pass commitlint, but release-please can’t parse feat(): x, so drop them.
• No space before the colon. feat : x fails commitlint and release-please.
• One blank line before the body, one before the footers.
• The spec says types aren’t case sensitive. commitlint’s default config wants them lower case, so write them lower case.

Reference

Types

Only feat and fix come from the spec. The rest are the Angular list that commitlint enforces by default. The section column is where release-please puts each type; “hidden” means left out of the changelog.

A release made only of hidden types doesn’t happen. Want a type that isn’t on the list? Add it to your commitlint config or the linter will reject it.

Major releases

Breaking changes

Either a ! before the colon:

feat(api)!: return frogs sorted by name

Or a footer:

feat(api): return frogs sorted by name

BREAKING CHANGE: clients that relied on insertion order must sort.

• Under the spec, the two mean the same thing, and you can use both at once.
• The footer must be capitals. BREAKING-CHANGE: with a hyphen also counts under the spec.
• semantic-release with no config doesn’t understand ! and releases nothing for that commit. The semantic-release guide has the two-line fix.

Last lines

Footers

Each footer is a token, then : or #, then a value. Tokens use a hyphen where a space would go. BREAKING CHANGE is the only token allowed a space.

The linter

commitlint default rules

What @commitlint/config-conventional 21.2.3 enforces. Errors fail the commit. Warnings print and let it through.

subject-case is the one that catches everyone. Any description starting with a capital fails, including OAuth token refresh. Merge commits, Revert "...", fixup! and bare version numbers are skipped by default.

Copy these

Commits to copy

A fix with a body and two footers:

fix(auth): stop the double submit

The button fired twice on slow connections.

Refs: #42
Reviewed-by: Sam

A revert. release-please lists it under Reverts and cuts a patch; semantic-release with no config releases nothing:

revert: feat(search): find frogs by location

Refs: a1b2c3d

If you’d rather be asked questions than remember any of this, Commitizen writes the message for you.

Honesty

What this doesn’t fix

Good commits get you the right version and a changelog. They don’t get anyone outside the repo to hear about the release. The changelog waits for people who go looking, and nobody goes looking.

That’s the part I built Merge & Tell for. It reads each merged pull request and drafts a post about it, and I read every one before it goes out. The updates page is it running on itself.