DEV Community

Cover image for An introduction to Conventional Commits
Jordan Harrison
Jordan Harrison

Posted on • Edited on

An introduction to Conventional Commits

As a student, i've always wondered if there is 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)]
Enter fullscreen mode Exit fullscreen mode

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: CHange Outside Runtime Environment - Update something without impacting the code (ex: readme update, CI/CD update...).

Examples

Some examples of the above would be

Commit with no body

feat: allow provided config object to extend other configs
Enter fullscreen mode Exit fullscreen mode
docs: correct spelling of CHANGELOG
Enter fullscreen mode Exit fullscreen mode

Commit with ! to draw attention to breaking change

feat!: send an email to the customer when a product is shipped
Enter fullscreen mode Exit fullscreen mode

Commit with scope and ! to draw attention to breaking change

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

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
Enter fullscreen mode Exit fullscreen mode

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

Top comments (2)

Collapse
 
stradivario profile image
Kristiqn Tachev

Hello there!

I am glad that you are researching such a things and you are on the right path!

Just one thing i need to say CHORE means change outside runtime environment package.json is actually part of the code itself and can lead to unpredicted scenarios even patches in npm community sometimes can lead to minor or major upgrades due to lack of knowledge unfortunate...

It is even better idea to remove the patch in your package.json for production application since at some point you are not sure which package will be installed and what could go wrong with it.

CHORE is more of an change on lint settings or readme.md or CI/CD settings which are not part of the runtime.

Cheers!
Keep the good work!

Collapse
 
jordharr profile image
Jordan Harrison

Wow I never knew that - I was assuming it was related to chore in English (something that is a menial task that has to be done) - thanks for the clarity!