Conventional Commits
Commit types
The commit contains the following structural elements to communicate intent to consumers of your library:
fix: a fix commit type addresses a bug in your codebase (this correlates with PATCH in Semantic Versioning).
feat: a feat commit type introduces a new feature to the codebase (this correlates with MINOR in Semantic Versioning).
BREAKING CHANGE: a commit that has a BREAKING CHANGE: footer or adds a ! after the type/scope introduces a breaking change in the API (correlates with MAJOR in Semantic Versioning). A BREAKING CHANGE can be part of commits of any type.
Types other than fix: and feat: are allowed, for example, @commitlint/config-conventional (based on the Angular convention) recommends build:, chore:, ci:, docs:, style:, refactor:, perf:, test:, actions:, and others.
Different footers other than BREAKING CHANGE: can be provided and follow a similar convention to the git trailer format.
Additional types are not mandatory according to the Conventional Commits specification and do not have an implicit effect on Semantic Versioning (unless they include a BREAKING CHANGE). A scope can be provided to the commit type to give additional contextual information and is placed in parentheses, e.g., feat(parser): add ability to parse arrays.
Commits MUST be prefixed with a type, which consists of a noun, feat (feature), fix (bug fix), etc., followed by the OPTIONAL scope, the OPTIONAL !, and the REQUIRED terminal colon and space.
The feat type MUST be used when a commit adds a new feature to your application or library.
The fix type MUST be used when a commit represents a bug fix for your application.
A scope MAY be provided after a type. A scope MUST consist of a noun describing a section of the code enclosed in parentheses, e.g., fix(parser):
A description MUST immediately follow the colon and space after the type/scope prefix. The description is a brief summary of the code changes, e.g., fix: array parsing issue when multiple spaces were in the string.
A longer commit body MAY be provided after the brief description, providing additional contextual information about the code changes. The body MUST begin one blank line after the description.
The body of a commit is free-form and MAY consist of any number of paragraphs separated by line breaks.
One or more footers MAY be provided one blank line after the body. Each footer MUST consist of a word token, followed by either a : or # separator, followed by a string value (this is inspired by the git trailer convention).
The footer token MUST use - instead of whitespace characters, e.g., Acked-by (this helps to differentiate the footer section from a multi-paragraph body). An exception is made for BREAKING CHANGE, which MAY also be used as a token.
The value of a footer MAY contain spaces and newlines, and parsing MUST terminate when another valid footer token/separator pair is observed.
Breaking changes MUST be indicated in the type/scope prefix of a commit or as a footer entry.
If included as a footer, a breaking change MUST consist of the uppercase text BREAKING CHANGE, followed by a colon, space, and description, e.g., BREAKING CHANGE: environment variables now take precedence over config files.
If included in the type/scope prefix, breaking changes MUST be indicated by a ! immediately before the colon. If ! is used, BREAKING CHANGE: MAY be omitted from the footer section and the commit description SHALL be used to describe the breaking change.
Types other than feat and fix MAY be used in commit messages, e.g., docs: update API reference documentation.
Information units that make up Conventional Commits MUST NOT be treated as case-sensitive by implementers, with the exception of BREAKING CHANGE, which MUST be in uppercase.
BREAKING-CHANGE MUST be synonymous with BREAKING CHANGE when used as a footer token.
Structure of a Commit Message
A commit message consists of the following parts:
Type: Indicates the type of change made in the code. The most common types are "fix" (bug fix), "feat" (new feature), and "BREAKING CHANGE" (breaking change).
Scope: (Optional) Provides more context about the type of change. For example, "fix(parser)" indicates that the bug fix was made in the "parser" module.
Description: A brief summary of the change made.
Body: (Optional) Additional information about the change, such as the reason for the change or steps to reproduce it.
Footer: (Optional) Used to include additional information such as the author's name or a tracking ticket identifier.
Examples of Commit Messages:
fix: fix error when parsing files with whitespace
feat: add support for file uploading
BREAKING CHANGE: change the authentication module API
fix!: fix error when parsing files with whitespace
feat!: add support for file uploading
docs: update API documentation
Additional Resources
Official Conventional Commits Specification:
Commitizen: A tool to facilitate writing commit messages:
Conventional Commits: VSCode plugin to facilitate writing commits:
Last updated