Conventional Commits - Why?????
Overviews
A good commit messages is alway better than a bad one. A good commit messages has a clear description by keywords such as: features, fixes, or breaking changes made and so on.
Why Use Conventional Commits
- Automatically generating CHANGELOGs.
- Automatically determining a semantic version bump (based on the types of commits landed).
- Communicating the nature of changes to teammates, the public, and other stakeholders.
- Triggering build and publish processes.
- Making it easier for people to contribute to your projects, by allowing them to explore a more structured commit history.
Commit message construction
The commit message should be structured as follows:
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
The commit contains the following structural elements:
- fix: type
fixwhich patches a bug in your codebase. - feat: type
featwhich introduces a new feature to the codebase. - BREAKING CHANGE: a commit that has a footer
BREAKING CHANGE:, or appends a!after the type/scope, introduces a breaking API change. A BREAKING CHANGE can be part of commits of any type. - types can be
build:,chore:,ci:,docs:,style:,refactor:,perf:,test:, and others. - footers other than
BREAKING CHANGE: <description>may be provided and follow a convention similar to git trailer format.
A scope is optional and only provides additional contextual information and is contained within parenthesis, e.g., feat(parser): add ability to parse arrays.
Examples
Commit message with description and breaking change footer
feat: allow provided config object to extend other configs
BREAKING CHANGE: `extends` key in config file is now used for extending other config files
Commit message with ! to draw attention to breaking change
refactor!: drop support for Node 6
Commit message with both ! and BREAKING CHANGE footer
refactor!: drop support for Node 6
BREAKING CHANGE: refactor to use JavaScript features not available in Node 6.
Commit message with no body
docs: correct spelling of CHANGELOG
Commit message with scope
feat(lang): add polish language
Commit message with multi-paragraph body and multiple footers
fix: correct minor typos in code
see the issue for details
on typos fixed.
Reviewed-by: Z
Refs #133
Specification
- 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
featMUST be used when a commit adds a new feature to your application or library. - The type
fixMUST 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 forBREAKING 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: updated 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.