Published March 18, 2021
Writing clear, concise commit messages enable you to work well with any team and get your best work out there.
Good commits can make the difference between a well-maintained product, and a terrible product. Well-written commits following a standardized format will enable viewers of your codebase to easily understand the type of change, what modules it affected, and why it occurred. Below, I will outline my format for commits, based on the Semantic Commits style popularized by the AngularJS team.
Most people don’t start thinking about their commits when they first start development (I get it, there’s a lot going on and a lot to learn)
But commits become especially important when you’re a part of a team.
When you enter a new repository, you want to be able to see how the project has developed over time. If you were to see commits like this:
Fix the thing Update stylesAdd the thing
(Note, these are actually not the worst examples—I’m sure you’ve seen worse)
You likely won’t be able to understand what happened, without reading the code changes in a commit itself.
However, contrast those with these commits:
fix(blog): Imported posts formatted correctly with new styles feat(blog): Update styles to reflect new design feat(blog): Add blog feed to site.
Looks great, so how do we do it?
The semantic commit contains 4 parts:
Here’s how it works:
So in our first example above, we might create:
feat(blog): Add blog feed to siteAdd the markdown plugin, generate pages, and create blog template.
You can use your own types, but here are the defaults:
Your scope can be as granular as you’d like and will likely change based on the complexity of the project. If you’re just starting off a project, you could omit the scope, but I highly recommend you consider it because it forces you to think very clearly about what you’re changing.
You want to summarize your commit with a single line. If you can’t, then you probably want to consider breaking the commit down into smaller pieces to make the work logical and self-contained.
A single line is good for the summary, but sometimes you want to add additional detail so that readers can see more about what you changed now that they know why you changed it.
Writing better commits will help you write better code. Simple practices like this force you into a mindset of craftsmanship and self-documenting projects.
Consider reading the original source The Karma Commit Message Format or this newer resource The Conventional Commits.
Once you’re going with semantic commits, you might want to enforce it as a standard on your projects! For something like this, you can use Commitizen(for validation) and Husky (for pre-commit hooks).
I will be following up with a guide on using pre-commit hooks to do linting, testing, and more in a future article.
Till then, happy coding.
May your code be functional, readable, and well-used.
Originally published at https://mweeks.dev.
Powered by Froala Editor