Skip to content

Draft — not approved. A working draft by UASK. It may change without notice.

Status: review · Version 1.0.0

Commit messages (Conventional Commits)

Summary

A commit message is the only documentation that is guaranteed to travel with a change. Conventional Commits adds a light, machine-readable structure to the first line — type(scope): summary — and a standard way to flag breaking changes. People can scan history quickly, and tools can decide the next semantic version and draft the changelog.

Rules

  • R1. The first line of a commit message MUST have the form type(scope): summary or type: summary, with a colon and one space after the type or scope.
  • R2. The type feat MUST be used for a new feature and fix for a bug fix; other changes SHOULD use one of docs, refactor, perf, test, build, ci, chore, style or revert.
  • R3. A breaking change MUST be marked with ! before the colon (feat(api)!: …), with a BREAKING CHANGE: <description> footer, or with both; the footer token MUST be upper case.
  • R4. The summary MUST describe what the change does, in the imperative mood (“add”, not “added”), and SHOULD be no longer than 72 characters including the prefix (Git itself suggests about 50 for the title).
  • R5. A body, when present, MUST be separated from the first line by a blank line and SHOULD explain why the change was made and what it affects, not repeat the diff.
  • R6. Footers MUST follow the body after a blank line, in the form Token: value or Token #value, with hyphens instead of spaces in tokens (Reviewed-by, Refs, Co-Authored-By).
  • R7. A commit SHOULD contain one logical change; unrelated changes SHOULD be split into separate commits or pull requests.
  • R8. When pull requests are squash-merged, the pull request title MUST follow R1–R4, because it becomes the commit message on the main branch.

Guidance

  • Scope is a short noun for the part of the system: feat(checkout):, fix(parser):. Agree a list in the repository so scopes stay consistent; leave it out when the change is global.
  • Mapping to SemVer. fix → PATCH, feat → MINOR, any breaking change → MAJOR. Other types do not change the version unless they are breaking.
  • Issue links go in the footer (Refs: #42) or in the pull request (Closes #42), not in the summary.
  • Automate the check. A commit-message hook or a CI step (for example commitlint) catches mistakes before review. Do not rely on memory.
  • Agents. Coding agents follow the same rules; an attribution footer such as Co-Authored-By: makes machine-written changes traceable.
  • Not for every repository. For a personal scratch repository the overhead may not pay off; for anything released or shared it does.

Explanation

Free-form messages (“fixes”, “wip”, “update”) make history hard to search and impossible to process automatically. The Git project’s own guidance already asks for a short summary line, a blank line and an explanatory body, because many tools show only the first line. Conventional Commits builds on that by standardising the first words of the summary, which lets a release tool read the history since the last tag and decide whether the next release is a patch, a minor or a major version.

Examples

Good:

feat(checkout): add pickup-point delivery option
Customers can choose a pickup point instead of courier delivery.
The option is hidden when the cart contains oversized items.
Refs: #128
fix(api)!: return 404 instead of 200 for unknown product ids
BREAKING CHANGE: clients that treated an empty 200 response as "not found"
must now handle HTTP 404.

Bad:

Fixed stuff and updated styles, also new delivery

Sources