The concept of good messages to go along with your commits to source control seems to be one of those things that people either completely follow or completely drop the ball on. Fortunately my work right now is predominantly solo and I only have myself to blame if my commit messages are unhelpful, but I still try to follow a few rules to save the sanity of myself in the future.
Rule #1: Good Messages Start With Good Story Cards
Some call them story cards, or tasks, or any number of other names for something that is a portion of work that must be completed from a less-manageable major task (aka an epic). Whatever you call them, many projects have some form of task list to work through and I leverage this list for my commit messages for later referencing. Several project management tools such as Jira or Mingle automatically assign cards to a number that increments as you go. The tool we use at my job unfortunately does no such thing, but I add a number to each card title manually to reap the same benefits. Each story card should have a basic title explaining what needs to happen. The description can go into more depth regarding the solution and other necessary information.
When I write up my commit messages, I start with the story card number for the work I’m submitting (you read that right – I try to keep it to one card per commit!) The beauty of providing the card number in your commit message is the ability to reference exactly what was done. If you need to go back to a week ago to figure out what changes were made that caused a new bug to crop up, you can look at the commit messages for the past week and see which cards were worked on and head over to your story board for further investigation.
Rule #2: Good Messages Are Descriptive
Consider for a moment that you’ve been tasked with going through the last month’s commits of a fellow developer. Perhaps looking through the changes can lead you to what’s causing this crazy new bug that just showed up. You bring up the source control manager and see something like this:
4/18/19 – committing stuff
4/15/19 – asdf
4/05/19 – before friday’s meeting
4/04/19 – did stuff
4/01/19 – product card
Sure, you can look through each file that was changed in each commit to get an idea of what happened… but what if there was a better way? What if each source control message gave you a brief synopsis of the change that was done for that commit. Also, what if they were more frequent? A lot could have happened between April 5th and April 15th! I try to make a commit at least once a day; several times a day if I’ve been making a lot of significant changes in a short period of time.
The important part is to add some value to each commit message, whether you expect future-you or a coworker (or replacement) to read them or not. This simple act could save someone a great deal of time, giving them the ability to reference each major set of changes at a glance instead of needing to inspect each one.
Rule #3: Good Messages Explain What, Not How or Why
Another benefit to linking your commit messages to your storyboard by card numbers is the beauty of not having to repeat yourself. If your cards are written descriptively and show the steps taken to solve the problem, create the feature, etc., you don’t need to write those things a second time in your source control because it can all be found if you follow the card number!
Your source control message should have some information in it though – I try to provide a sentence briefly explaining what changes were made. Some examples sentences could be “Added checklist for customer item selection" or "Removed discount button from main page". In the case of a card that spans over a longer period of time I will do several commits with a brief update of the work that happened in that span of time: "Implemented binding creation for Salesforce login feature".
If someone needs to trace back into the source control for the bug that showed up last week, they can get a birds eye view of the changes that went on in this period by reading the messages. If they see a message that sticks out, perhaps relating to the problem section of code, they can easily reference the number and check out the more detailed view in the related story card. The story card will provide them with the hows and whys of the changes that were made.
Good Messages Look Like…
So what do good source control commits look like? Here’s a few examples of recent commits from my major project at work:
Card #213 – Updated formatting on Reports Form
Card #213 – Added Reports Form and first report to get and update all unprocessed orders
Card #208 – Updated query for discounts
Card #205 – Only requiring SOM_SalesOrderID in close/email dialog form
Card #204 – Moved SOM_UserDef5 and SOM_FOB updates ahead of SalesOrder XML creation
TLDR: When making source control commits, I try to keep my messages brief, descriptive, and maintain a regular formatting style. I also make an effort to keep one major change set or card per commit to avoid muddying up the change sets and messages.