Conventional Commits Cheat Sheet
Conventional Commits spec: types, scope, breaking changes, and examples.
Conventional Commits gives commit messages a predictable structure that tools can use for changelogs and release versioning. A good message names the user-visible or maintenance change without repeating implementation noise.
Commit format
The required header is type, an optional scope, a colon, and a concise description. A blank line may separate the header from a body and footers.
type(scope): description
Optional explanation of context and behavior.
Optional-Footer: value
feat(search): support filtering by file extension
| Part | Rule |
|---|---|
type | Short category describing the change. |
(scope) | Optional noun describing the affected area. |
: | Required separator after type or scope. |
description | Short imperative-style summary; avoid a trailing period. |
Common types
Types are conventions rather than a closed keyword list, but these names work well with release tooling and team guidelines.
| Type | Typical meaning |
|---|---|
feat | Add user-visible functionality. |
fix | Correct a defect. |
docs | Documentation-only change. |
style | Formatting or whitespace with no behavior change. |
refactor | Restructure without changing behavior. |
perf | Improve performance. |
test | Add or correct tests. |
build | Build system or dependency changes. |
ci | Continuous integration configuration. |
chore | Maintenance outside production behavior. |
revert | Revert an earlier change. |
Scope and description
Scope is optional and should be stable enough to help readers filter history. Use a specific area such as api, parser, or checkout, not an internal file name that changes frequently.
fix(api): reject malformed pagination cursors
refactor(parser): separate tokenization from validation
ci: cache pnpm store in pull request jobs
Prefer an imperative, lowercase description: “add”, “fix”, or “remove” rather than “added”, “fixes”, or “we changed”. Keep the first line easy to scan in logs.
Breaking changes
Mark an incompatible API or behavior change with ! after the type or scope, and explain it in the body or a BREAKING CHANGE: footer. The footer token is case-sensitive in the specification.
feat(api)!: replace offset pagination with cursors
BREAKING CHANGE: clients must send a cursor returned by the previous page.
refactor(parser)!: remove legacy token names
SemVer mapping
When commits drive releases, a common mapping is fix to PATCH, feat to MINOR, and any breaking change to MAJOR. The project’s release tool may apply additional rules.
| Commit signal | SemVer effect |
|---|---|
fix | PATCH: backward-compatible bug fix. |
feat | MINOR: backward-compatible functionality. |
! or BREAKING CHANGE: | MAJOR: incompatible public change. |
| Other types | Usually no release bump by themselves. |
Examples
feat: add dark mode toggle
fix(ui): preserve focus after copying text
docs: clarify local development setup
perf(parser): reduce repeated allocations
test: cover empty input behavior
revert: revert "feat: add dark mode toggle"