3 steps to write good commit messages

Piotr Romanowski

Commit

“If a thing is worth doing, it’s worth doing well” 

 

As you may know tinyPM is integrated with such SCM tools like Github, Beanstalk, Bitbucket and Stash. Thanks to this integration you can group all commits in a logical structure that corresponds to your backlog structure in tinyPM.

This is actually an awesome thing because you can easily access not only the history of particular user story, but also its development history.

And indeed, it’s all about communication. Almost all software projects are collaborative team projects. A well written commit message is critical to communicate the context of change to team members. Moreover, later on you can easily check and understand the context without going back to it again and again. This is how you can save your time and resources.

Now, this is not only developer’s or project manager’s dream about having everything in the right order and place. Let’s stop dreaming – it can all be done properly here and now!
There is only one condition – a whole team needs to be willing to write great commit messages. And now it’s time to show you how to do that.

 

 

Here are 3 rules to follow:

 

1. KISS – Keep It Simple Stupid 
A good commit message should be concise and consistent.

If the change is trivial that where explanation is not required, single line is sufficient enough as a commit message.
It should be written in an imperative style like “fix a typo”:

If applied, this commit will fix the typo.

 

If a commit is more complicated we need to write a subject (in an imperative style) and provide explanation.
Within this explanation, we should focus on describing why this change was made and how it benefitted the project.

It’s very important that a commit should refer to one logical change at a time. What does it mean? It’s not correct to write message like: “fix the filtering bug, the searching bug, and add attachments to the user story”. Here we should create three, separate commits:

fix filtering bug 

fix searching bug

add attachments to user story

 

2. Use three magic questions to provide sufficient context
Peter Hutterer wrote that good commit message should answer three, fundamental questions:

- Why is it necessary?
Concise description of the reason why a commit needs to be done. What does it fix? What feature does it add? How does it improve performance or reliability?

- How does it address the issue?
For trivial patches this part can be omitted. There should be a high-level description of what the approach was.

- What effects does the patch have?
(In addition to the obvious ones, this may include benchmarks, side effects, etc.)

 

These three questions will help you to provide all necessary information and context for future reference.

 

You can easily link commits to tasks or user stories in your tinyPM. Simply include a user story #id in the commit message #512 and the commit will show up on this particular story card:

Add a list of recommended products #512

For more instructions about commit syntax please check tinyPM documentation.

 

 

3. Do not use excuses!

We all know that sticking to the rules can be a pain in the neck. However, this is often necessary in order to achieve certain goals. Our goal is to write great commit messages, therefore, we need to adhere to such rules.

And yes, there will be a lot of excuses like: “but it works”, “we didn’t have time” or “I’m the only one working on this” and a dozen of others. Finding excuses is way easier than being consequent. Therefore, we need to think about it in the big picture – think how many benefits we can get.

Just remember that good programmers can be recognized by their legacy. Good commit history will help others to start work on such projects readily without any problems figuring it all out.

This should become a habit that will constantly benefit a whole team in terms of productivity and efficiency as well as a sense of satisfaction.

 
The last word belongs to Chris Beams: “(…) just think how much time the author is saving fellow and future committers by taking the time to provide this context here and now.”


Leave a Reply