Conventional Commits
Photo by Kelly Sikkema on UnsplashConventional Commits is a widely adpoted standard way of writing a commit message.
Overview
Before proceeding further, please peruse the full spec from the Conventional Commits offical website.
The short summary of a conventional commit message is:
<type>[(scope)][!]: <description>
<blank line>
[body]
<blank line>
[footer(s)]
Types
The standard recommends the use of the following types:
- build: Changes that affect the build system or external dependencies
- chore: A code change that is neither a
feator afix(example: bumping versions of dependencies) - ci: Changes to CI configuration files and scripts
- docs: Documentation only changes
- feat: A new feature
- fix: A bug fix
- perf: A code change that improves performance
- refactor: A code change that neither fixes a bug nor adds a feature
- revert: A commit that reverts a previous commit
- style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
- test: Adding missing tests or correcting existing tests
- wip: Indicates this commit is a Work-In-Progress
Scopes
Every repo should have a list of scopes clearly defined in the repo’s README file. Commit message may use a scope to clarify what part of the codebase this commit touches. For multiple scopes, use a comma separation.
Breaking Change
If the commit introduces a breaking change, it must be indicated using an exclamation (!) after the type/scope and before the colon (:).
Description
The description is a short summary of the code changes. The description shall be written in imperative. The first line, including type, scope and description shall not exceed 50 characters. TIP: If you set your git config core.editor=vim, it will automatically highlight when you are going over 50 characters. Description shall start with a lower case.
Here are some correct and wrong examples for description:
✅ add foo to main menu
❌ adding foo to main menu
❌ added foo to main menu
A good way to think about writing in imperative, is to try to fill in the blank of the sentence:
If merged, this commit will _________________________.
What you write in the blank will usually be in imperative.
Body
A commit body is free-form and may consist of any number of newline separated paragraphs. Try to add more context about the commit focussing on WHY this change was introduced rather than WHAT code was changed. Most developers can see the commit diff and easily figure out the WHAT part - answering the WHY question adds value to the commit message. Remember, you yourself may be wondering about WHY you made this change on your own commit a few months down the road.
Footer
One or more footers may be provided one blank line after the body. Each footer must consist of a word token, followed by a :-) to separate words.
This is an non-exhaustive example list of possible footers:
BREAKING-CHANGE: This commit will break the code for database records in the old schema.
Closes: JIRA-123
Refer: JIRA-456
Reviewed-by: Bob [email protected]
Signed-off-by: Alice [email protected]
Why
Conventional commits standardize and make it easy to read commit messages. It also helps in writing tools to parse commit messages are automatically generate changelogs, or suggest semantic version number updates based on the presence of fix (patch version is incremented) or feat (minor version is incremented) etc. Tools can also parse the token: value syntax of the footers to process information contained therein.
