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](https://www.conventionalcommits.org/en/v1.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 | Type | SemVer impact | When to use | |------|--------------|-------------| | `feat` | MINOR | Introduces a new feature | | `fix` | PATCH | Patches a bug | | `docs` | none | Documentation changes only | | `style` | none | Formatting, whitespace, missing semicolons | | `refactor` | none | Code change that is neither a fix nor a feature | | `perf` | none | Performance improvement | | `test` | none | Adding or correcting tests | | `build` | none | Build system or external dependency changes | | `ci` | none | CI/CD configuration changes | | `chore` | none | Routine tasks, maintenance, tooling | | `revert` | varies | Reverts a previous commit | 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`: | Footer | Purpose | |--------|---------| | `BREAKING CHANGE: <desc>` | Documents a breaking API change | | `Refs: #123` | Links to a related issue or PR | | `Reviewed-by: Name` | Credits a code reviewer | | `Co-authored-by: Name <email>` | Credits a co-author | | `Fixes: #456` | Closes an issue on merge | 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 | Commit type | Resulting version bump | |-------------|----------------------| | `fix` | PATCH (0.0.x) | | `feat` | MINOR (0.x.0) | | Any type with `BREAKING CHANGE` or `!` | MAJOR (x.0.0) | 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)