I’ve always tended to write commit messages by answering the question “What did I do?”, but I learned a different approach recently which tends to produce much more expressive commits, which are often more terse as well. Compare the following:
|“What did I do?”||“What do things look like now?”|
|Fixed a bug whereby active links were displaying in the wrong colour||Active links now display as blue|
|Changed the styling of the popup for clarity||The popup now more clearly displays the review description|
|Fixed styling bug in previous commit||The styling added in the previous commit now only gets applied to the modal|
|Added a list of reviewed versions with icons to the security column||The security column now displays a list of reviewed versions|
Ok, so not all of these are fantastic commit messages (they’re all real from recent work I’ve done). This approach isn’t a magic formula but it helps me to focus on what’s most relevant, and I feel like the messages on the right are more useful.
An important insight is that although at the time the distinction between implementing a feature/fixing a bug/adding a tweak seems important, when scanning through a list of commits, it’s probably the actual behaviour which which is going to be most useful (caveat: if you have a story ID or ticket reference then it’s probably worth including).