Conventional Git Commit

Conventional Git Commit

MANDATORY RULE: Every git commit message in this project MUST follow the Conventional Commits 1.0.0 specification. No exceptions. A commit with a non-conforming message MUST be rejected and rewritten before proceeding.

Produces git commit messages that conform to the Conventional Commits 1.0.0 specification — a lightweight, machine-readable convention that maps directly to Semantic Versioning.

Commit Message Structure

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Every part of this structure is defined by strict rules:

• type — Required. A noun indicating the category of change.
• scope — Optional. A noun in parentheses narrowing the affected area, e.g. fix(parser):.
• ! — Optional. Appended immediately before : to flag a breaking change.
• description — Required. A short, imperative-mood summary immediately after the colon+space.
• body — Optional. One blank line after the description; free-form paragraphs.
• footers — Optional. One blank line after the body; Token: value or Token #value pairs.

Core Types

Only feat and fix have implicit SemVer meaning. All others carry no automatic version bump unless accompanied by a breaking change marker.

Breaking Changes

Two equivalent methods exist — use either or both:

Method 1 — ! after type/scope:

feat(api)!: remove deprecated endpoint /v1/users

Method 2 — BREAKING CHANGE footer:

feat(api): remove deprecated endpoint /v1/users

BREAKING CHANGE: /v1/users is removed. Migrate to /v2/users.

Both combined (maximum visibility):

feat(api)!: remove deprecated endpoint /v1/users

BREAKING CHANGE: /v1/users is removed. Migrate to /v2/users.

A breaking change MUST use uppercase BREAKING CHANGE in the footer. BREAKING-CHANGE is a valid synonym.

Workflow: Writing a Commit Message

Step 1 — Identify the primary intent: Determine whether the change adds a feature, fixes a bug, or is maintenance/housekeeping.

Step 2 — Choose the type: Pick the single most appropriate type from the table above. If a change spans multiple types, split it into separate commits.

Step 3 — Determine scope (optional): Choose a short noun representing the affected module, component, or area: auth, parser, api, ui, deps.

Step 4 — Detect breaking changes: Ask: "Does this change require consumers to update their code?" If yes, apply ! and/or add a BREAKING CHANGE footer.

Step 5 — Write the description:

• Use imperative mood: "add", "fix", "remove", "update" — not "added", "fixes", "removing"
• Keep under 72 characters
• Do not capitalize the first letter (consistency convention)
• Do not end with a period

Step 6 — Add body if needed: Explain the why, not the what. Wrap at 72 characters. Separate from description with one blank line.

Step 7 — Add footers if needed: Reference issues, reviewers, or co-authors using Token: value format.

Quick Examples

feat: add OAuth2 login support

fix(auth): prevent session expiry on page refresh

docs: update API reference for /v2/search endpoint

refactor(parser): extract token validation into separate module

perf(db): add index on users.email for faster lookup

chore(deps): bump lodash from 4.17.20 to 4.17.21

feat!: drop support for Node.js 14

BREAKING CHANGE: minimum required Node.js version is now 18.

fix: prevent racing of requests

Introduce a request id and a reference to the latest request.
Dismiss incoming responses other than from the latest request.

Reviewed-by: Alice
Refs: #123

Footer Conventions

Footers follow git trailer format — Token: value or Token #value:

Token names use hyphens instead of spaces (e.g. Co-authored-by). BREAKING CHANGE is the sole exception — it may contain a space.

Scope Guidelines

Scopes are project-specific nouns. Common patterns:

• By module: feat(auth):, fix(parser):, test(api):
• By layer: refactor(db):, perf(cache):, build(docker):
• By UI area: feat(login):, style(nav):, fix(modal):

Keep scopes consistent within a project. Define the allowed scope list in a contributing guide or commitlint config if the team is large.

SemVer Mapping

Tools such as semantic-release and standard-version parse commit history to automate this version bump.

Common Mistakes to Avoid

• Vague descriptions: fix: bug → fix(auth): handle null token in session middleware
• Wrong type: using chore for a bug fix; use fix
• Multiple intents in one commit: one commit = one logical change
• Missing blank line before body or footers: parsers rely on the blank line separator
• Lowercase breaking change in footer: MUST be BREAKING CHANGE (uppercase)
• Missing space after colon: feat:description is invalid; must be feat: description

Additional Resources

Reference Files

• references/commit-types.md — Detailed guidance and examples for every commit type, including edge cases and when types overlap
• references/advanced-patterns.md — Breaking changes, multi-footer commits, revert commits, monorepo scopes, and tooling integration (commitlint, semantic-release)