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>(<scope>)[!]: <description>

[optional body]

[optional footer(s)]

Rules:

• Separate header, body, footers with a blank line.
• Keep the header on one line.
• Scope is required - always include a scope in parentheses.
• Put ! immediately before : to mark a breaking change (e.g. feat(api)!: ..., refactor(core)!: ...).

Choose a type

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

User-facing types

• feat: introduce a new feature (user-facing)

  • Use when: Users see new behavior, capabilities, or options
  • Examples: new CLI flags, new UI components, new API endpoints, new configuration options

• fix: bug fix (user-facing)

  • Use when: Users see corrected behavior; something broken now works
  • Examples: fixing crashes, handling edge cases, correcting incorrect output

Documentation types

• docs: documentation-only changes (.md files, comments in dedicated docs files)
  • Use when: changing .md, .txt, or dedicated documentation files
  • When NOT to use: Code files (.ts, .js, .py, etc.) containing comments, inline docs, or workflow instructions → use feat, fix, refactor, etc. based on the actual code change
  • Example: updating workflow instructions in a TypeScript component is feat or fix, not docs

Maintenance types

• refactor: refactor that neither fixes a bug nor adds a feature

  • Use when: code structure changes but behavior is identical
  • Examples: renaming variables/functions, extracting utilities, reorganizing imports

• perf: performance improvement

  • Use when: code runs faster or uses less memory
  • Examples: optimizing algorithms, reducing allocations, caching results

• test: add or adjust tests

  • Use when: only test files change (.test.ts, .spec.ts, test/ directory)
  • When NOT to use: if production code also changes, use the type that matches the production change

• build: build system/dependencies

  • Use when: build configuration, bundlers, compilers, or dependency management
  • Examples: package.json changes, Cargo.toml, Makefile, bundler config

• ci: CI configuration/scripts

  • Use when: CI/CD pipelines, GitHub Actions, deployment scripts
  • Examples: .github/workflows/, Jenkinsfile, deployment scripts

• chore: maintenance tasks

  • Use when: general maintenance that doesn't fit other categories
  • Examples: updating lint rules, cleaning up dead code, updating tooling configs

• style: formatting (whitespace, missing semicolons, etc.)

  • Use when: only formatting changes, no logic changes
  • When NOT to use: if any logic changes, use the appropriate type

• revert: revert a previous commit

  • Use when: undoing a previous commit entirely
  • Format: revert: <original-commit-message>

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)

Required scope

Use scope to clarify the area impacted. Scope is required for all commits.

Format:

type(scope): description

Guidelines:

• Use a short noun: api, auth, ui, db, cli, deps, docs, agent, lint, build.
• Use repo/module/package name when working in a monorepo.
• If unsure, use a generic scope like core, general, or misc.

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".
• Describe actual content, not generic categories. Name what was added/changed, not that "rules" or "principles" were added.

Examples:

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

Bad examples (vague, generic):

docs(agent): add behavioral guidelines and core principles
docs(agent): add agent operating principles
docs(agent): add behavior rules

Good examples (specific, concrete):

docs(agent): add rules for dead code removal, build verification, security, debugging, architecture, and tool usage

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 <email@example.com>

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>