I’ve written crappy commit messages in the past and I’ve picked up a few tricks over time that help me write helpful descriptions.
A good commit message should be helpful to the next developer that looks at your code.
Let’s look at some poor commit messages
git log -3 4dc1e4654 fix css a1a378d24 spelling fix 3fb78d433 css change
These descriptions are vague. Changed css in what? Mention what feature or part of the codebase you changed the css in.
git log -1 e7792a29 Launched Hubspot API integration
Let’s say the above Hubspot API integration commit had 45 changed files. A year from now, you left the company and your integration needs to be changed. Another developer looks at this commit and three questions come up.
- Was there a ticket / user story opened for this feature?
- What is the pull request for this feature?
- Are there docs?
Let’s make it easier it for them.
A descriptive commit message
When I merge my pull request into the master branch, I squash the pull request commits into one commit because intermediate commits likely have breaking tests and the developers don’t need to see granular details from my work.
That squashed single commit looks something like this:
Ticket-108 Launched Hubspot API Integration https://github.com/my_company/dpp/pull/1369 https://jira.com/link-to-jira-ticket https://companywiki.com/link-to-wiki-article-on-integration
The first line is a quick one line description of what was done. Notice the ticket number in front of the description. Add an empty line.
The next few lines are going to be links. I add a GitHub pull request link, a link to the ticket from Jira / Asana / whatever ticketing tool your company uses. The final url is to the documentation I created for this integration.
The next poor guy that has to revise my code will have documentation and breadcrumbs to follow to understand how the code was integrated into the codebase.