conventional-commits

name	conventional-commits
description	Write, review, and validate commit messages following the Conventional Commits v1.0.0 specification. Use when: (1) crafting a git commit message for any change, (2) reviewing or correcting an existing commit message, (3) choosing the right commit type for a change, (4) deciding how to mark a breaking change, (5) writing multi-line commits with body and footers, or (6) understanding how commits map to SemVer bumps (PATCH/MINOR/MAJOR). Covers all standard types: feat, fix, docs, chore, refactor, perf, test, build, ci, style, revert.
allowed-tools	Bash(git *)

<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

Type	Use for	SemVer
feat	New feature	MINOR
fix	Bug fix	PATCH
docs	Documentation only	none
style	Formatting, whitespace (no logic change)	none
refactor	Code restructure (not a fix or feature)	none
perf	Performance improvement	none
test	Adding or fixing tests	none
build	Build system, dependencies (npm, gradle…)	none
ci	CI configuration (GitHub Actions, CircleCI…)	none
chore	Maintenance not fitting above types	none
revert	Reverts a previous commit	none

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