Improving Your Change Logs - The bluejava Git Commit Message Format

"There is nothing permanent except change." – Heraclitus

Git-ing things done

So, you and your team manage your code changes with Git. Great! But what commit message format has your team adopted? None? A tacit agreement to "be clear and concise"? Or do you have an actual written and specified format that you all conform to?

I have been using Git for some time - and have always strived to be a good Git citizen (A good gitizen if you will… or maybe you won't…) - using short descriptive messages, atomic commits, etc. But admittedly, I had no standard or guide that I followed. Different commits sometimes used different grammatical moods ("added" vs. "adding" vs. "add") or even different words ("added" vs. "built" vs "enhanced") to refer to the same type of change.

A quick review of popular GitHub repositories reveals that most developers have a similar approach. Here are some commit messages from some popular repositories:

• "Release 2.1.1" (dragula)
• "Changes" (JAWS)
• "grunt" (bootstrap)
• "Update addons.js" (React)

These kinds of change log entries are not very useful. They mostly act as "placeholders" for a dated change - and information about the nature of the change or why it was made is unclear; or must be deduced by looking at the "diff". (Not to pick on these developers or these projects - I also am guilty of these kinds of log entries - hence this endeavor!)

The benefits of a consistent and informative change log message are wide ranging - starting with making it much easier to visually scan down commits list and find changes relevant to your search. Additionally, following a specific format opens the door to grep'ing and extracting useful information from your change logs programmatically.

It's a real productivity gain to use your commit logs to:

• List out all new features since your last release
• Locate bug introductions faster by skipping non-code changes in your git bisect runs
• List out changes to a particular subsystem
• Review the impact of a feature (wrt bugs, etc)
• Answer many other questions regarding your changes over time

For large projects and/or teams this could result in huge time savings. And for smaller projects, its another opportunity to realize those cumulative benefits from multiple small improvements!

The Search For Best Practices

So I did some poking around and found some guides from the Atom Organization, Typo3, one derived from AngularJS by Stephen Parish, and another from the Karma project (previously Testacular - an Angular group project). These are all preceded and likely influenced by the original GIT project code contribution guide.

Essentially, these guides espouse a similar set of recommendations: recognizing some line length limits, keeping the mood/voice/tense consistently imperative, and having a standard set of types (and optionally a consistent set of scopes) that describe each commit.

Stephen's felt like the closest to what I was looking for, so that guide provided a solid basis for my first crack at a bluejava Git Commit Message Format.  In fact I could very well have just adopted Stephen's guidelines as-is and improved greatly upon what I had been doing.

Making a Clear Commitment

But there were a few changes I felt improved upon the format, so I created this derivative. Changes include:

• types are ALL CAPITAL LETTERS to clearly distinguish them, and make them easier to filter/grep
• The list of commit types is slightly different than others. ("chore" becomes "MAINT", "style" becomes "FORMAT", "refactor" is gone, and a new breaking change type called "BREAK")
• The order of the list of types is important – when multiple types apply, the first type in the list should be used
• Multiple types may also be specified (see guide for details).
• Some recommendations such as not starting your subject line summary with a capital letter and omitting a period at the end have been dropped. I saw no value in controlling those details. (arguments to the contrary are welcomed!)
• This format guide will live on Github and will be versioned and upgraded/updated over time. Forking of this guide is possible and welcomed.

View the complete guide here on Github. I will publish it initially as version 0.5.0 (and use SemVer conventions, as best as they apply to non-code). Once I've spent some time applying this to my own changes, I will move it to 1.0.

I encourage developers and development teams to standardize their commit messages if they haven't already. Point your team members to this guide - or fork this guide and customize it for your needs.

And of course I'd love to hear any ideas you all have to improve the format. 

Quick Reference

This is also present on the guide itself, and contained within the repository for the guide - but I am including it here too for convenience. I saved this to my desktop so I can easily display it whenever I make a commit: