Conventional Commits Specification

CONVENTIONAL_COMMITS.md

Conventional Commits

The Conventional Commits Specification is a lightweight convention on top of commit messages which provides an easy set of rules for creating an explicit commit history, making it easier to write automated tools on top of your codebase. This convention agrees with Semantic Versioning, by describing the features, fixes, and breaking changes made in those commits.

Structure of a Conventional Commit

According to this specification, a commit message should be structured as follows:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Let's look at each of these structural element below!

The Commit <type> Prefix

Every commit message should be prefixed with a term that describes in one word the type of change involved in a commit. These prefixes can be one of the types below:

• feat: a new feature is introduced with the changes
• fix: a bug fix has occurred
• chore: changes that do not relate to a fix or feature and don't modify src or test files (for example updating dependencies)
• refactor: refactored code that neither fixes a bug nor adds a feature
• docs: updates to documentation such as a the README or other markdown files
• style: changes that do not affect the meaning of the code, likely related to code formatting such as white-space, missing semi-colons, and so on.
• test: including new or correcting previous tests
• perf: performance improvements
• ci: continuous integration related
• build: changes that affect the build system or external dependencies
• revert: reverts a previous commit

The Commit Description

Following the commit type, the description is a short subject line should be a short description written in all lowercase with a character limit to encourage concise, succinct descriptions.

The Commit Body

The commit body can contain a more detailed explanation about the commit. We can these details as Markdown as well.

The Commit Footers

The footers may contain further details about a commit, including external links, Issue# Refs, or Author details, etc.

In addition to these details, a commit footer can have an optional type called BREAKING CHANGE: which is same as ! after the type(scope): commit prefix (e.g. fix!:), indicating a breaking change.

NOTE: A BREAKING_CHANGE can be part of commits of any type.

Why use Conventional Commits

Conventional Commits help achieve the following things:

• 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

The structural elements in a Commit Message are useful to communicate intent for Semantic Versioning. For example:

• A commit of the type fix patches a bug in your codebase. This correlates with PATCH in Semantic Versioning
• A commit of the type feat introduces a new ferature to the codebase. This correlates with MINOR in Semantic Versioning
• A commit which includeas a footer with the optional type BEAKING_CHANGE: along with a prefix type like feat: or fix:, or an ! appended to the <type+(optional_scope) prefix like fix!, introduces a breaking API change. This correlates with MAJOR in Semantic Versioning.

Sample Conventional Commit Message Examples

Let's see some examples of some hypothetical conventional commit messages.

• 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

feat!: send an email to the customer when a product is shipped

• Commit message with (scope) and ! to draw attention to breaking change

feat(api)!: send an email to the customer when a product is shipped

• Commit message with both ! and BREAKING_CHANGE in footer

chore!: drop support for Node 6

BREAKING CHANGE: 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: prevent racing of requests

Introduce a request id and a reference to latest request. Dismiss
incoming responses other than from latest request.

Remove timeouts which were used to mitigate the racing issue but are
obsolete now.

Reviewed-by: Z
Refs: #123

That's all! Now you have everything that you need to know to start using the Conventional Commits Specification in your Git contributions on your project. With this simple upgrade, you can now create more meaningful commits, which convey the most information to all the members involved, allowing everyone to clearly follow the development of the project over time and space.

If you want to read the full specifications list, you can find it in the Conventional Commits Specification page here.

Thank you for reading... 🙏