Commit with Intent

The success of git has brought a new generation of committers to open source projects. That being said, it also makes us take a look at how we commit our code and what we can do to improve our commit messaging.

Certain pitfalls come into mind when looking at commit messages. For one, using -m (a shortcut tag to inline your commit messages) does not provide enough context for a peer to be able to thoroughly understand what the commit is actually achieving. Examples of shortcut commit messages include:

• Fixed a bug!
• Problem solved
• Issue resolved

All of the above are short commit messages that have zero context to what your commit actually does. Think about the pull request reviewer in this scenario. They would first need to go read line by line the code that you have written, then decipher what bug this might have fixed. Instead of a five minute pull request review this could stretch into a thirty minute review.

A better commit message…

Fix for incorrect date on Admin Interface Admin Interface was displaying the incorrect date on the profile page. The reason for this was how we were specifying the date to the incorrect timezones of the users account. The fix was to simply translate the current time to the timezone appropriate for the user's account.

As you can see from the commit message above, before we ever get to review the pull request code we can tell exactly what we are looking for. This makes the pull request take less time to review and gets us back on track to developing. As well, if we have to go back and check our commits, this will be an easier task then sorting through commits with messages such as Problem Solved.

Additional thoughts to keep in mind are to make sure that your summary is 50 characters or less. This will make the commit look nice as you won’t see … within the subject to description. The detailed description of the commit needs to be 1 to 2 paragraphs explaining what all changed within the code base and why these changes were made. Unordered lists may be used on larger commits to explain several changes.

Lastly don’t be afraid to reference how you achieved the solution. For instance did you find the solution on Stack Overflow? If so, add that link into the commit. This will be a nice reference especially if you have to go back and fix another similar problem. Also, it will let your coworkers/peers be able to understand how you came to this solution.

As much of a pain as they might be, commit messages are important to the development process. Writing descriptive messages allows your team to fully understand the decisions you made and why. It may also improve your likelihood of getting your PR accepted into open source projects.

Originally published at madebymunsters.com.