conventional-commits

name	conventional-commits
description	Writes and reviews Conventional Commits commit messages (v1.0.0) to support semantic versioning and automated changelogs. Use when drafting git commit messages, PR titles, release notes, or when enforcing a conventional commit format (type(scope): subject, BREAKING CHANGE, footers, revert).

Conventional Commits (v1.0.0)

Use the Conventional Commits spec to produce consistent commit messages that are easy to parse for changelogs and semantic versioning.

Commit message format (canonical)

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

[optional body]

[optional footer(s)]

Rules:

• Separate header, body, footers with a blank line.
• Keep the header on one line.
• Put ! immediately before : to mark a breaking change (e.g. feat!: ..., refactor(api)!: ...).

Choose a type

The spec allows any type, but these are common and widely supported by tooling:

• feat: introduce a new feature (user-facing)
• fix: bug fix (user-facing)
• docs: documentation-only changes
• refactor: refactor that neither fixes a bug nor adds a feature
• perf: performance improvement
• test: add or adjust tests
• build: build system/dependencies
• ci: CI configuration/scripts
• chore: maintenance tasks
• style: formatting (whitespace, missing semicolons, etc.)
• revert: revert a previous commit

Default choice when unsure:

• If users see new behavior → feat
• If users see corrected behavior → fix
• Otherwise → chore or a more specific maintenance type (refactor, build, ci)

Optional scope

Use scope to clarify the area impacted.

Format:

type(scope): description

Guidelines:

• Use a short noun: api, auth, ui, db, cli, deps, docs.
• Use repo/module/package name when working in a monorepo.
• If scope adds no clarity, omit it.

Description (subject)

Write the description as a short summary of what the change does.

Guidelines:

• Use imperative mood: “add”, “fix”, “remove”, “update”.
• Avoid ending punctuation.
• Be specific; avoid “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 the body to explain motivation, constraints, or high-level implementation notes.

Guidelines:

• Prefer complete sentences.
• If helpful, include:
  • why the change was needed
  • what approach was chosen
  • notable trade-offs

Example:

refactor(parser): simplify tokenization

Replace the regex pipeline with a small state machine to reduce backtracking.

Footers (optional)

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

• breaking change details
• issue references
• metadata used by tooling

Examples:

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

Breaking changes

Mark breaking changes in one (or both) of these ways:

1. Add ! in the header:

feat(api)!: remove deprecated v1 endpoints

2. Add a BREAKING CHANGE: footer (recommended when you need an explanation):

feat(api): remove deprecated v1 endpoints

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

Reverts

Use the revert type when undoing a previous change.

Example:

revert: feat(auth): add passwordless login

This reverts commit 1a2b3c4.

Semantic versioning mapping (typical)

Common mapping for automated version bumps:

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

When asked to “write a commit message”

Collect missing inputs quickly:

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

Then produce:

1. A conventional header
2. Optional body (only if it adds clarity)
3. Optional footers (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>