# 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.
# Format: [REFERENCE] HOW to DO WHAT
[#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.