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: Help another developer quickly understand what was done in a commit Help undo specific changes (a feature, for example) Prepare change notes for a release Tips for writing better commit messages. Specify the type of commit: feat. The new feature you're adding to a particular application fix: A bug fix style: Feature and updates related to styling refactor: Refactoring a specific section of the codebase test: Everything related to testing docs: Everything related to documentation chore: Regular code maintenance Specify a task number Use the imperative mood in the subject line 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.
