Type	Purpose	SemVer
`feat`	New feature	MINOR
`fix`	Bug fix	PATCH
`docs`	Documentation only	-
`style`	Formatting, no code change	-
`refactor`	Code change, no feature/fix	-
`perf`	Performance improvement	-
`test`	Adding/fixing tests	-
`build`	Build system, dependencies	-
`ci`	CI configuration	-
`chore`	Maintenance tasks	-
`revert`	Revert previous commit	-

Breaking Changes

feat!: send email when product shipped

feat(api)!: change response format

chore!: drop support for Node 6

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

Examples

Simple Commits

feat: add user authentication
fix: resolve memory leak in cache
docs: update API documentation
style: format code with prettier
refactor: extract validation logic
perf: optimize database queries
test: add unit tests for auth module
build: upgrade webpack to v5
ci: add GitHub Actions workflow
chore: update dependencies

With Scope

feat(auth): add OAuth2 support
fix(parser): handle empty arrays
docs(readme): add installation guide
refactor(api): simplify error handling

With Body

fix: prevent request racing

Introduce a request id and 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.

With Footer

fix: correct minor typos in code

Reviewed-by: John Doe
Refs: #123

Breaking Change in Footer

feat: allow config object to extend other configs

BREAKING CHANGE: `extends` key in config file is now used
for extending other config files.

Breaking Change with ! and Footer

chore!: drop support for Node 6

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

Revert Commit

revert: let us never again speak of the noodle incident

Refs: 676104e, a215868

Specification Rules

MUST

Commits MUST be prefixed with a type (feat, fix, etc.)
Type MUST be followed by colon and space
Description MUST immediately follow the colon and space
feat MUST be used for new features
fix MUST be used for bug fixes
Breaking changes MUST be indicated by ! before : OR BREAKING CHANGE: footer
BREAKING CHANGE MUST be uppercase
Footer token MUST use - instead of spaces (e.g., Reviewed-by)

MAY

Scope MAY be provided after type: feat(parser):
Body MAY be provided after description (blank line between)
Footer MAY be provided after body (blank line between)
Types other than feat and fix MAY be used
! MAY be used with BREAKING CHANGE: footer

Case Sensitivity

Types: case-insensitive (lowercase recommended for consistency)
BREAKING CHANGE: MUST be uppercase
BREAKING-CHANGE: synonym for BREAKING CHANGE

SemVer Mapping

Commit Type	SemVer Bump	Version Change
`fix:`	PATCH	1.0.0 → 1.0.1
`feat:`	MINOR	1.0.0 → 1.1.0
`BREAKING CHANGE` or `!`	MAJOR	1.0.0 → 2.0.0

Breaking changes override type — fix!: results in MAJOR bump.

Changelog Integration

Conventional Commits map directly to changelog entries:

Commit Type	Changelog Section
`feat`	Added
`fix`	Fixed
`perf`	Changed
`refactor`	Changed
`docs`	(usually omitted or Changed)
`BREAKING CHANGE`	Highlight in Changed/Removed
`revert`	Removed or Fixed
Security fixes	Security

Automated Changelog Generation

Tools like conventional-changelog, semantic-release, or release-please can:

Parse commit messages
Generate CHANGELOG.md entries
Determine next version number
Create releases automatically

See changelog skill for CHANGELOG.md format.

Common Patterns

Feature Development

git commit -m "feat(users): add profile page"
git commit -m "feat(users): add avatar upload"
git commit -m "test(users): add profile page tests"
git commit -m "docs(users): document profile API"

Bug Fix with Reference

git commit -m "fix(auth): resolve session timeout (#142)"

Breaking Change Flow

# Deprecate first
git commit -m "feat(api): add v2 endpoint

DEPRECATED: /api/v1/users will be removed in next major version"

# Later, remove
git commit -m "feat(api)!: remove v1 endpoints

BREAKING CHANGE: /api/v1/* endpoints have been removed.
Use /api/v2/* instead."

FAQ

What if commit fits multiple types?

Split into multiple commits when possible. This makes history more organized.

What if I used wrong type?

Before merge: git rebase -i to edit history. After release: not critical — commit will be missed by automated tools.

Do all contributors need to use this?

No. Use squash merging and maintainers can write proper message for the merge.

How to handle reverts?

revert: <original commit subject>

Refs: <commit SHA>

Git Configuration

Commit Template

Set up git to use template:

git config commit.template .gitmessage

See assets/commit-msg.template for template file.

Pre-commit Validation

Use assets/validate-commit-msg.sh with git hooks or CI.

Tools

Tool	Purpose
commitlint	Lint commit messages
commitizen	Interactive commit helper
conventional-changelog	Generate changelogs
semantic-release	Automated releases
release-please	GitHub release automation

Critical Prohibitions

Do not use vague messages ("fix stuff", "update", "wip")
Do not mix unrelated changes in single commit
Do not omit breaking change indicators
Do not use non-standard types without team agreement
Do not forget blank line between description and body

Agent Workflow for Commit Messages

MANDATORY: Before proposing branch name, commit message, or PR description, the agent MUST:

Check all changed files using git status or git diff --name-only
Review actual changes using git diff (staged and unstaged)
Analyze ALL modifications — not just the files mentioned in conversation
Base proposals on complete changeset — include all affected files, not partial list

Workflow Steps

# Step 1: Get list of all changed files
git status --short

# Step 2: Review actual changes (for unstaged)
git diff

# Step 3: Review staged changes
git diff --staged

# Step 4: Use the complete changeset to propose:
#   - Branch name
#   - Commit message
#   - PR description

Output Format

When user asks for commit message, provide:

Branch name options (3 variants using conventional prefixes)
Commit message variants (short/medium/detailed)
PR description (summarized, not duplicating full changelog)

All proposals MUST be based on the actual git diff output, not assumptions.

Templates

commit-msg.template — Git commit message template
validate-commit-msg.sh — Validation script

commits

Conventional Commits

Quick Reference

Format

Common Types