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:
<type>([optional scope]): <short description> [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
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
It updates the version to
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
If you want to read up on some more rules and real-world examples, here are some fantastic resources.
- Conventional Commits website
- Angular Conventional Commits
- Angular examples
- Daily.dev examples
- Visual Studio Code plugin
I hope you found this helpful. Conventional Commits helped me make commit messages so much easier and more precise for my team.