An introduction to Conventional Commits

As a student, i had always wondered if there was a standard around commit messages. I thought it would make sense for them to be standardised, and when I started my new role I learned about Conventional Commits - and it just makes sense! I see a lot of people don't follow any rules and, when it comes to working with a team, without standardisation the commit log can become quite chaotic and uninformative.

Conventional Commits is a specification for adding human and machine-readable meaning to commit messages. It is a lightweight convention on top of commit messages that provides an easy set of rules to help you create an explicit commit history, making it easier to write automated tools on top of. This convention dovetails with SemVer, by describing the features, fixes, and breaking changes made in commit messages.

Conventional Commits have the following structure:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

With Conventional Commits, there are multiple types of commit you can make.

  • feat: Add a new feature to the codebase (MINOR in semantic versioning).

  • fix: Fix a bug (equivalent to a PATCH in Semantic Versioning).

  • docs: Documentation changes.

  • style: Code style change (semicolon, indentation...).

  • refactor: Refactor code without changing public API.

  • perf: Update code performances.

  • test: Add test to an existing feature.

  • chore: Update something without impacting the user (ex: bump a dependency in package.json).

Examples

Some examples of the above would be

Commit with no body

feat: allow provided config object to extend other configs
docs: correct spelling of CHANGELOG

Commit with ! to draw attention to breaking change

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

Commit with scope and ! to draw attention to breaking change

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

Commit with multi-paragraph body and footer

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.

Story-ref: #1234

Benefits

Readability

Commits are more descriptive, making it easier for teammates and stakeholders to read and understand them. It also makes it easier to contribute.

Changelog

Allows you to automatically generate a changelog.

Version Control

Helps to automatically determine a semantic version bump based on the types of commits landed.

Revert changes

If only one action is made per commit, it makes it simpler to revert a change or git conflict

Avatar for Jordan Harrison

Written by Jordan Harrison

Software Developer I, CXE @ Charles River Labs

Loading

Fetching comments

Hey! 👋

Got something to say?

or to leave a comment.