The best commit message out there. The one that tells you absolutely nothing about anything.
Commit messages are a funny thing. They’re not very valuable when you submit them, yet when a bug pops up in production or you’re building a release, knowing the right place to look (especially if it’s not your code change) can save hours.
The commit message is one of those things you do so that you can reap the benefits when needed. Sort of like locking your door at night before you go to bed. You don’t expect to need those locks, but when you do, you’re grateful you had them in place and locked.
So what can make a great commit message? First I think it’s better to try and ask, what makes a great commit? This question can actually be trickier to answer but I think answering it, helps us write a better commit message.
A good commit, can best be seen as a lot of commits. The reason being is that when you commit often you can end up with a best of both world scenario.
You see some would prefer one giant chunk of completed code to complete a feature. This let’s you see the entire solution together as one. It can be difficult to review or push changes to a main branch, one-by-one. The good news is, most source control solutions now offer a way to squash (combine) all of the new commits on a branch before merging them into main, making it incredibly easy to accomplish this.
However, seeing individual commits can let you break things down more easily. You can get an idea of how the changes developed over time and it can help you pinpoint issues. You can also write more frequent commit messages instead of one really long message on a single massive commit. Oh and if you ever need to switch gears and work on that production bug ASAP, having your in progress work already committed makes it easy to switch to your main branch without losing any work.
Now that we know we want to have lots of little commits, let’s talk about what to put in the commit message. There are a couple of key details to include in your commit message based on your branching strategy. If you have a good branching strategy your commit message can contain more or less information as needed but you typically want to try and cover the following:
Include the ID of the related work ticket.
Include the type of commit.
Include a brief description of the change.
These three items make up a tasty commit stew and can be viewed as: ID-Type: Message. Let’s look at couple of examples.
23489-Feature: Added new items to the drop down on search page
23489-Bug: Fixed the drop down from not opening completely
89012-Refactor: Cleaned up old, duplicate code for invoicing
1203-Dependencies: Updated dependencies ahead of new features
Each of these commit messages provides enough detail for you to be able to tie back the code changes directly to the work item they belong to as well as what the change is so you can easily help identify potential issues.
When pushing these changes to a main branch you then have two options, you can either hang on to the individual commits (which can be useful for future debugging) or you can squash them all together and push the changes as a whole feature to the main branch (which will give you a cleaner history for the code base).
At the end of the day, there’s no right way to write a commit message. There are however, wrong ways… The key is to do yourself and your fellow developers a favor and make it as easy as possible to identify what the code changes are.