Conventional Commits

Why Conventional Commits

• Easy-to-follow structure for commit messages.
• Clearly states the nature of changes.
• Ensures uniformity in commit messages across teams.
• Enables automated versioning and changelog generation.
• Makes commit history easy to browse.
• Allows the specification of 'scope' for more clarity.
• Has a special notation for breaking changes.
• Facilitates better understanding among team members.
• Makes the review process efficient.
• Helps in future troubleshooting with descriptive commit messages.

Structure

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Official Website {.link-arrow}

• feat: add jwt support
• feat!: breaking change in API
• feat(ui)!: redesign user profile page
• fix: fix SQL injection vulnerability
• fix(database): resolve data race condition
• docs: update setup section of README
• style(login): correct indentation in login component
• refactor: refactor user database schema
• perf: optimize user retrieval code for faster response
• test: add tests for jwt authentication
• test(payment): add tests for the payment gateway
• chore: update build script
• chore(deps): update dependencies
• build(docker): update Dockerfile to use node 14
• ci: add job for integration tests
• revert: revert commit a1b2c3d4e5f

{.bold-first}

• Commits MUST be prefixed with a type, which consists of a noun, feat, fix, etc., followed by the OPTIONAL scope, OPTIONAL !, and REQUIRED terminal colon and space.
• The type feat MUST be used when a commit adds a new feature to your application or library.
• The type fix 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 codebase surrounded by parenthesis, e.g., fix(parser):
• A description MUST immediately follow the colon and space after the type/scope prefix. The description is a short summary of the code changes, e.g., fix: array parsing issue when multiple spaces were contained in string.
• A longer commit body MAY be provided after the short description, providing additional contextual information about the code changes. The body MUST begin one blank line after the description.
• A commit body is free-form and MAY consist of any number of newline separated paragraphs.
• 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 :<space> or <space># separator, followed by a string value (this is inspired by the git trailer convention).
• A footer’s token MUST use - in place of whitespace characters, e.g., Acked-by (this helps differentiate the footer section from a multi-paragraph body). An exception is made for BREAKING CHANGE, which MAY also be used as a token.
• A footer’s value MAY contain spaces and newlines, and parsing MUST terminate when the next valid footer token/separator pair is observed.
• Breaking changes MUST be indicated in the type/scope prefix of a commit, or as an entry in the footer.
• 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 :. 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 your commit messages, e.g., docs: update ref docs.
• The units of information that make up Conventional Commits MUST NOT be treated as case sensitive by implementors, with the exception of BREAKING CHANGE which MUST be uppercase.
• BREAKING-CHANGE MUST be synonymous with BREAKING CHANGE, when used as a token in a footer.