Conventional Commits

Conventional Commits 1.0.0

Write commit messages following the Conventional Commits 1.0.0 specification so history is explicit and drives SemVer bumps, changelogs, and release automation.

When to Use

• Composing any commit message (git commit).
• Choosing the right type/scope for a change.
• Indicating a breaking change.
• Writing a multi-paragraph body or footers (e.g. Refs:, Reviewed-by:).
• Validating an existing message against the spec.

Format

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

[optional body]

[optional footer(s)]

• type: a noun such as feat or fix, followed by an optional scope, an optional !, then a REQUIRED colon and space.
• description: a short summary, immediately after the : .
• body: optional; begins one blank line after the description; free-form paragraphs.
• footer(s): optional; begin one blank line after the body; each is Token: value or Token #value.

Procedure

1. Pick the type that best matches the change (see table). If it fits more than one, make separate commits.
2. Add a scope if it usefully names the affected area: fix(driver): ....
3. Write the description: imperative mood, concise, lowercase, no trailing period.
4. Mark breaking changes with ! before the colon and/or a BREAKING CHANGE: footer.
5. Add body/footers if context, reasoning, or references are needed.
6. Commit, preferably passing the message via -m (repeat -m for body/footer paragraphs):

   git commit -m "feat(parser): add ability to parse arrays"
   # with body + footer:
   git commit -m "fix: prevent racing of requests" \
     -m "Introduce a request id and a reference to the latest request." \
     -m "Refs: #123"
   

Types (and SemVer mapping)

Only feat and fix are mandated by the spec; the rest are the widely used Angular/commitlint set. Types other than feat/fix have no implicit SemVer effect unless they carry a breaking change. Teams MAY define additional types.

Breaking Changes

Indicate a breaking change in either place (or both):

• In the prefix: put ! immediately before the colon — feat!: ... or feat(api)!: .... The description then describes the break, and the footer MAY be omitted.
• In a footer: BREAKING CHANGE: <description>. The token MUST be uppercase (BREAKING-CHANGE is an accepted synonym). A breaking change may accompany any type.

feat!: drop support for Node 6

BREAKING CHANGE: use JavaScript features not available in Node 6.

Scope

A scope is a noun in parentheses naming a section of the codebase: feat(lang): add Polish language, fix(parser): handle empty input. It is optional.

Body & Footers

• The body begins one blank line after the description and may span multiple paragraphs.
• Footers begin one blank line after the body. Each footer token uses - instead of spaces (e.g. Reviewed-by, Acked-by, Refs), except BREAKING CHANGE. Separator is : or #.
• A footer value may contain spaces and newlines; parsing ends at the next valid footer token.

fix: prevent racing of requests

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

Reviewed-by: Z
Refs: #123

Reverts

The spec does not mandate revert behavior. Recommended form: the revert type with a footer referencing the reverted commit SHAs.

revert: let us never again speak of the noodle incident

Refs: 676104e, a215868

Casing

Units of a Conventional Commit are case-insensitive, except BREAKING CHANGE, which MUST be uppercase. Pick one casing for types and be consistent (this repo uses lowercase, e.g. fix:, ci:).

Examples

Why It Matters

Conventional Commits enable automatic CHANGELOG generation, automatic SemVer bump detection (fix→PATCH, feat→MINOR, breaking→MAJOR), clearer history, and triggering of build/publish pipelines. It pairs with the conventional-branch (branch names) and semantic-versioning (release versions) skills.