Wednesday, June 29, 2011

Write testable Git commit messages

Having been a project manager for a couple of projects, I often find myself having to decipher team mate's code commits by digging into code diffs. Take for example.

# Poor commit message with lack of information
fix bugs on email template

Hmm. What bugs is he trying to fix? How would I know if it's really fixed? What if he wrote instead

# Slightly better with description of what the bug is
fix bugs on email template that caused HTML misalignment

Ah, that's better. At least now there's a WHAT context that I can focus on when looking through the diffs. This could possibly be enhanced with a HOW context.

# Even better message
fix bugs on email template that caused HTML misalignment by declaring inline styles on elements

Great, now the only thing left to the piece of the puzzle is WHO determined that those were bugs?

# Almost perfect
[#31] fix bugs on email template that caused HTML misalignment by declaring inline styles on elements

Ok a reference to the bug request on Github would help me find out who requested the issue.

This leads me to the concept of writing good testable commit messages. Example,

# A great testable commit message.
[#55] Added inline styles on HTML elements to fix bug that caused misalignment on email templates

That's a great commit message because it can be tested. I could fire up the email mailer and check that the email is indeed aligned properly. And it saves the project manager and the other team mates valuable time by cutting down time spent deciphering what the code was meant to do. Even more important if the commit messages were to be viewed many months down the road.


George Mendoza said...
This comment has been removed by the author.
George Mendoza said...

Hi Jason,

I usually prefer to emphasize the WHY instead of the HOW in git commits:

[#100] Email templates should not have misalignments.

I think this is still in line with your suggestion of testable git commits, since it describes in testable terms what the commit aims to accomplish.

Also, without the technical details, the commit can also be read by the client. If he were so inclined :)

As for the HOW, I usually leave it out, thinking that Ruby code is readable enough to show what is happening. Still, your post makes me wonder about the pros/cons of adding the HOW to commit messages :)



Nazeer said...

Nice reading about commit messages. We do pair programming. Some time we may have different way of committing messages. This post will surely shed some lights and make uniform style.

Thanks George