conventional-commits

name	conventional-commits
description	Write and review Conventional Commits commit messages (v1.0.0) for semantic versioning and changelogs. Use when drafting git commit messages, PR titles, release notes, or enforcing conventional commit format like `type(scope): subject`, `BREAKING CHANGE`, footers, and `revert`.

Conventional Commits (v1.0.0)

Use Conventional Commits spec to keep commit messages consistent and easy for changelog and semantic-versioning tools to parse.

Commit message format (canonical)

<type>[optional scope][!]: <description>

[optional body]

[optional footer(s)]

Rules:

• Separate header, body, and footers with blank line
• Keep header on one line
• Put ! right before : to mark breaking change, like feat!: ... or refactor(api)!: ...

Choose type

Spec allows any type, but these are common and widely supported:

• feat: new user-facing feature
• fix: user-facing bug fix
• docs: docs-only change
• refactor: refactor with no feature and no bug fix
• perf: performance improvement
• test: add or adjust tests
• build: build system or dependency change
• ci: CI config or scripts
• chore: maintenance work
• style: formatting only, like whitespace or missing semicolons
• revert: revert earlier commit

Default choice when unsure:

• If users get new behavior → feat
• If users get corrected behavior → fix
• Otherwise → chore or more specific maintenance type like refactor, build, or ci

Optional scope

Use scope when it makes impacted area clearer.

Format:

type(scope): description

Guidelines:

• Use short noun: api, auth, ui, db, cli, deps, docs
• In monorepo, use repo, module, or package name if useful
• If scope adds no clarity, leave it out

Description (subject)

Write description as short summary of what change does.

Guidelines:

• Use imperative mood: add, fix, remove, update
• No ending punctuation
• Be specific; avoid vague words like stuff, changes, update things

Examples:

feat(auth): add passwordless login
fix(api): handle empty pagination cursor
chore(deps): bump react to 18.3.0

Body (optional)

Use body for motivation, constraints, or high-level implementation notes.

Guidelines:

• Prefer complete sentences
• If useful, include:
  • why change was needed
  • what approach you chose
  • notable trade-offs

Example:

refactor(parser): simplify tokenisation

Replace regex pipeline with small state machine to reduce backtracking.

Footers (optional)

Footers are key/value-like lines at end. Use them for:

• breaking change details
• issue references
• tooling metadata

Examples:

Refs: #123
Closes: #456
Co-authored-by: Name <[e-mail]>

Breaking changes

Mark breaking changes in one or both ways:

1. Add ! in header:

feat(api)!: remove deprecated v1 endpoints

2. Add BREAKING CHANGE: footer. Best when change needs explanation:

feat(api): remove deprecated v1 endpoints

BREAKING CHANGE: /v1/* endpoints are removed; migrate to /v2/*.

Reverts

Use revert type when undoing earlier change.

Example:

revert: feat(auth): add passwordless login

This reverts commit 1a2b3c4.

Semantic versioning mapping (typical)

Common automated version-bump mapping:

• fix → patch
• feat → minor
• any breaking change (! or BREAKING CHANGE:) → major

When asked to “write commit message”

Collect missing inputs fast:

• What changed? (1–2 sentences)
• Scope or module? (optional)
• User-facing? (feature vs fix vs chore)
• Breaking? (yes/no; migration note if yes)
• Any issue IDs to reference?

Then produce:

1. Conventional header
2. Optional body, only if it adds clarity
3. Optional footers like Refs:, Closes:, BREAKING CHANGE:

Ready-to-use templates

Minimal:

<type>: <description>

With scope:

<type>(<scope>): <description>

Breaking change with explanation:

<type>(<scope>): <description>

BREAKING CHANGE: <what breaks and how to migrate>