Git basics: Conventional commits

— 3 minute read

When it comes to writing commit messages, we all get blackouts. It's very hard sometimes to describe a commit message and make it meaningful.

And that's where conventional commits can help you. This is a set of rules to help you describe a commit message.

This is not a golden standard in the industry, some companies use it, and some have their commit structure. Always check with your team what they use.

The conventional commit structure

The basic structure for conventional commits looks like this:

([optional scope]): 

[optional body]

[optional footer]

Let's dive a bit deeper into the meaning of these elements.

  • type: This is a must-have type. We'll dive into the types in a second.
  • optional scope: A optional flag to indicate an isolated scope
  • short description: Your general description for the commit
  • optional body: A more detailed description of the commit, this is optional but handy for bigger commits
  • optional footer: Can state breaking changes and reference issues by ticket number

Right, let's have a look at the types as they are an important aspect here.

  • build: Changes that affect the build system like gulp, npm, etc
  • ci: Changes made to the CI configuration like Travis, Circle, Actions
  • chore: Other changes that don't modify src or test files
  • docs: Documentation only changes
  • feat: A new feature
  • fix: Fixed a bug
  • perf: Code changes that improve performance
  • refactor: A code change that's not particularly a bug or new feature
  • revert: Revert a previous commit
  • style: Changes to styling like white-space, formatting, semi-colons)
  • test: Add or fix tests

Some examples

Let's look at some samples, as they give the best understanding of what's going on.

In the example below, we see a new feature being introduced. It also states some more details in the body and references a ticket which can be set to #done.

feat: holiday-themed devcard

Our DevCard now features a holiday theme for both Halloween and Christmas!
This also includes a link pointing to Chris' article on how to embed it on your GitHub Profile.

DD-267 #done

Below, you can see a build commit that affects only a specific scope, the extension. It updates the version to 3.8.0

build(extension): version 3.8.0

The following introduces a breaking change and includes a ! to draw attention to breaking changes.

chore!: drop Node 6 from testing matrix

BREAKING CHANGE: dropping Node 6 which hits end of life in April

This one is a ci issue where we introduce a new Kubernetes helper.

ci: use pulumi common new kubernetes helpers

Reference material

If you want to read up on some more rules and real-world examples, here are some fantastic resources.

I hope you found this helpful. Conventional Commits helped me make commit messages so much easier and more precise for my team.

Thank you for reading, and let's connect!

Thank you for reading my blog. Feel free to subscribe to my email newsletter and connect on Facebook or Twitter