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.

More posts
  • Being a recovering workaholic

    Workaholism is a problem, and something we've experienced ourselves. But as a dad, Joey would much rather risk not conquering the world than risk missing out on experiencing time with his kids.

    Read More
  • My Week with Disney's MagicBand
    A UX Dream Come True

    Last fall, my family and I went to Disney World for the first time. We decided at the last minute to go, so we opted to stay in a timeshare and rent a car off Disney property. The experience was great (of course, because it's the Happiest Place on Earth), but we noticed we were the only people at the park without these awesome looking wristbands.

    Read More
  • Build Your Product For Day One

    We work with companies of all sizes. But our team always looks at the immediate needs and problems our client faces and then defines a solution for day one.

    Read More