Tips for Writing Good Commit Messages

Throughout my career, I’ve worked on many projects, some of which had the same problem. What was the problem? It was a useless commit history. So in this article, I’d like to share my opinion on how to write good commit messages that would make your git log useful and improve your code review process.

Why do we need and what do we expect from a commit message?

If you’re working alone on a small pet project, you might not need a good commit history, so you can write any messages. But if you’re working on a team on a long-term project a good history is a must-have. It could help to:

1. Help another developer quickly understand what was done in a commit
2. Help undo specific changes (a feature, for example)
3. Prepare change notes for a release

Tips for writing better commit messages.

1. Specify the type of commit:

   1. feat. The new feature you're adding to a particular application
   2. fix: A bug fix
   3. style: Feature and updates related to styling
   4. refactor: Refactoring a specific section of the codebase
   5. test: Everything related to testing
   6. docs: Everything related to documentation
   7. chore: Regular code maintenance

2. Specify a task number

3. Use the imperative mood in the subject line

4. Convey WHAT changed and WHY it changes in a concise way

Let's take a look at a couple of examples of bad and good messages.

Worse:

Fixed a bug

Commit

Debugging

.

OG-5531

I think why the messages above are worse is obvious

Bad:

feat: I changed filtering logic

fix OG-5334 I added a filter for messages

What is wrong with the lines above? They are short and show what changed, but they don’t give any context. The reader will unlikely understand easily which filtering logic was changed and why it was changed. The same is fair for the second line. Let’s try to improve them

Good:

feat: OG-5531 Use ranges in dates filters in API

fix: OG-5334 Don’t process duplicate messages

Now they look better. We understand what feature was added and what bug was fixed and how.

All the tips above can be applied to writing Merge Requests descriptions. That conversion would improve a code review process by giving the reviewer a brief understanding of what the MR is about. In the description, you could also add some screenshots of the UI if it was changed. If your MR contains several commits you could squash them into one and add a list of changes based on the commits in the description.