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
  • Filtering File Upload Logging with Paperclip

    Made By Munsters projects typically rely on Rails backends, and that means that we often enlist Paperclip to help us handle file uploads. Typically we push the file uploads from the client side as part of a single RESTful request, sending the Base64 encoded file data alongside other pieces of the resource.

    Read More
  • How To Find Success As A Remote Intern

    Made By Munsters made the transition to working remote easier by utilizing the best tools for communication and project management. Those tools have helped me learn that finding success as a remote intern involves discipline, communication and motivation.

    Read More
  • Build a Text Date Input with ngModel parsers and formatters

    Angular's ngModel and its two-way binding to backing model properties is great. The directive automatically handles copying values between the DOM input elements and the JavaScript object that's configured to collect the form data.

    Read More