conventional-commits

<live_context> Staged changes (summary): !git diff --cached --stat 2>/dev/null || echo "(nothing staged)"

Staged diff: !git diff --cached 2>/dev/null | head -300 || echo "(nothing staged)"

Recent commits (style reference): !git log --oneline -8 2>/dev/null || echo "(no commits yet)" </live_context>

Table of Contents

• Format
• Types and SemVer impact
• Breaking changes
• Examples
• Non-obvious rules
• Choosing the right type
• SemVer cheatsheet

Format

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

• type: lowercase noun (see table below)
• scope: optional noun in parentheses describing the affected section, e.g. feat(auth):
• description: imperative, present tense, no period at end, immediately after ": "
• body: free-form; begins one blank line after description
• footers: one blank line after body; follow git trailer format (Token: value or Token #value)

Types and SemVer impact

Any type + BREAKING CHANGE → MAJOR.

Breaking changes

Two ways to signal a breaking change (can combine both):

1. ! after type/scope (visible at a glance):

feat(api)!: remove deprecated v1 endpoints

2. BREAKING CHANGE: footer (required if you need a description):

feat: allow config object to extend other configs

BREAKING CHANGE: `extends` key now used for extending config files

Both together:

chore!: drop support for Node 6

BREAKING CHANGE: use JavaScript features not available in Node 6.

Examples

Simple fix:

fix: prevent racing of requests

Feature with scope:

feat(lang): add Polish language

Fix with body and footers:

fix: prevent racing of requests

Introduce a request id and a reference to latest request. Dismiss
incoming responses other than from latest request.

Remove timeouts which were used to mitigate the racing issue but are
obsolete now.

Reviewed-by: Z
Refs: #123

Revert with footer references:

revert: let us never again speak of the noodle incident

Refs: 676104e, a215868

Docs with no body:

docs: correct spelling of CHANGELOG

Non-obvious rules

• NEVER add Co-Authored-By trailers to commit messages. This project does not use authorship footers.
• Types are case-insensitive in parsing, but BREAKING CHANGE footer token must be uppercase.
• BREAKING-CHANGE (hyphen) is a valid synonym for BREAKING CHANGE in footers.
• Footer tokens use - instead of spaces (e.g. Reviewed-by), except BREAKING CHANGE.
• Footer separator is either ": " (colon-space) or " #" (space-hash for issue refs): Refs #123.
• A footer value may span multiple lines; parsing stops at the next valid Token: or Token # pair.
• When a commit fits multiple types, split into multiple commits instead of picking one.
• Wrong type used before merge? Ask the developer to fix manually with an interactive rebase. Claude Code cannot run interactive commands. After release, the commit is simply missed by automation tools — not catastrophic.
• Squash workflows: lead maintainer can rewrite messages at merge time; contributors don’t need to follow the spec perfectly on every WIP commit.

Choosing the right type

Is it a new user-facing capability?         → feat
Is it fixing incorrect behavior?            → fix
Is it changing docs/comments only?          → docs
Is it improving speed/memory?               → perf
Is it reorganizing code (no behavior Δ)?    → refactor
Is it adding/fixing tests only?             → test
Is it CI pipeline config?                   → ci
Is it build tooling or dependency updates?  → build
Is it undoing a previous commit?            → revert
Everything else (scripts, config, etc.)?    → chore

SemVer cheatsheet

fix→PATCH, feat→MINOR, BREAKING CHANGE→MAJOR