Commit messages (Conventional Commits)
Summary
A commit message is the only documentation that is guaranteed to travel with a change. Conventional Commits
adds a light, machine-readable structure to the first line — type(scope): summary — and a standard way to
flag breaking changes. People can scan history quickly, and tools can decide the next semantic version and
draft the changelog.
Rules
- R1. The first line of a commit message MUST have the form
type(scope): summaryortype: summary, with a colon and one space after the type or scope. - R2. The type
featMUST be used for a new feature andfixfor a bug fix; other changes SHOULD use one ofdocs,refactor,perf,test,build,ci,chore,styleorrevert. - R3. A breaking change MUST be marked with
!before the colon (feat(api)!: …), with aBREAKING CHANGE: <description>footer, or with both; the footer token MUST be upper case. - R4. The summary MUST describe what the change does, in the imperative mood (“add”, not “added”), and SHOULD be no longer than 72 characters including the prefix (Git itself suggests about 50 for the title).
- R5. A body, when present, MUST be separated from the first line by a blank line and SHOULD explain why the change was made and what it affects, not repeat the diff.
- R6. Footers MUST follow the body after a blank line, in the form
Token: valueorToken #value, with hyphens instead of spaces in tokens (Reviewed-by,Refs,Co-Authored-By). - R7. A commit SHOULD contain one logical change; unrelated changes SHOULD be split into separate commits or pull requests.
- R8. When pull requests are squash-merged, the pull request title MUST follow R1–R4, because it becomes the commit message on the main branch.
Guidance
- Scope is a short noun for the part of the system:
feat(checkout):,fix(parser):. Agree a list in the repository so scopes stay consistent; leave it out when the change is global. - Mapping to SemVer.
fix→ PATCH,feat→ MINOR, any breaking change → MAJOR. Other types do not change the version unless they are breaking. - Issue links go in the footer (
Refs: #42) or in the pull request (Closes #42), not in the summary. - Automate the check. A commit-message hook or a CI step (for example commitlint) catches mistakes before review. Do not rely on memory.
- Agents. Coding agents follow the same rules; an attribution footer such as
Co-Authored-By:makes machine-written changes traceable. - Not for every repository. For a personal scratch repository the overhead may not pay off; for anything released or shared it does.
Explanation
Free-form messages (“fixes”, “wip”, “update”) make history hard to search and impossible to process automatically. The Git project’s own guidance already asks for a short summary line, a blank line and an explanatory body, because many tools show only the first line. Conventional Commits builds on that by standardising the first words of the summary, which lets a release tool read the history since the last tag and decide whether the next release is a patch, a minor or a major version.
Examples
Good:
feat(checkout): add pickup-point delivery option
Customers can choose a pickup point instead of courier delivery.The option is hidden when the cart contains oversized items.
Refs: #128fix(api)!: return 404 instead of 200 for unknown product ids
BREAKING CHANGE: clients that treated an empty 200 response as "not found"must now handle HTTP 404.Bad:
Fixed stuff and updated styles, also new deliverySources
- Conventional Commits 1.0.0 — CC BY 3.0; rules R1, R3 and R6 paraphrase the specification. Accessed 2026-11-20.
- Git documentation — git-commit, “Discussion” — GPL-2.0; summary line and body conventions. Accessed 2026-11-20.