When I first started out with Git I was told I could save time by just using the -m flag to write the commit message at the same time. "Amazing!" I thought, "I've just saved 2 seconds. 10x Dev here I come"
Context is King
Now I realise that I was missing the opportunity to add valuable context to my commit messages. This extra context makes it easier to understand what's changed and why, which has two main advantages:
You don't have to rely on memory
Your team don't have to rely on your memory
Imagine there is an issue with the number of active Gatling users, so you want to work out why the active users were changed. What commit message is clearer?
Gatling active users fixed
Or this?
fix(load-test): Gatling active users
This change seeks to fix the active user and request rate currently in place for load-test.
Removing the ObtainAccessTokenDuringTest scenario from the simulation flattens the active users during test, as this was not working as intended.
Additionally the access token should live for 60 minutes, eliminating the need for obtaining a new one during load tests < 60 minutes.
The first commit message only tells you what has changed, which really should be obvious from your code change anyway.
Whereas the second commit message tells you what & why. The why is the context and is not always obvious from the code change.
I like to follow the rule of concise commit message headers and detailed descriptions. People should be able to glance at it and have a rough idea of what it is about without going into the full description. But importantly the detail is there if required.
Following Standards
You can take this a step further by also working to a commit message standard in your team/organisation. An example that I use is a variation of Conventional Commits.
With this standard in place you can also then use Git Hooks to automatically validate your commit messages, or use something like the GitHub Action action-commit-lint to do this.
Why?
A shared understanding of what a good commit message should looks like
A shared understanding is great because that makes reviewing other people's Pull Requests (PRs) much easier. Additionally it makes it easier to help others improve their commits during review by having something to point to.
PRs are not just about reviewing source code, the commit messages are also important for the reasons I mentioned previously.
Automate Changelogs
One of the biggest benefits I've found with following a standard is that it allows you to automate Changelog creation. This helps to reduce the number of tasks required for the person doing the release and makes sure the Changelog is always the same format.
Features
- feat: some cool feature
- !feat: this is a breaking change
Fixes
- fix(api): fix some bug
Other
- refactor: make class more readable
- chore(deps): bump X version
- docs: improve README.md
Conclusion
Yes, commit messages aren't the most sexy topic in software engineering, but I think they are an overlooked and important aspect of healthy collaboration.
Half of our job is reviewing other people's code, and I always have much more respect for that person if they have clean and well described commits. It's one of the differences between a Junior and a Senior.
If your team doesn't already follow a commit standard then why not suggest it and implement validation? It's such an easy change and can really improve your code health.
Top comments (0)