Good Commit Messages Give Devs Meaning, Purpose

Adding clarity to commit messages significantly helps fellow developers, and this short blog will share some best practices for writing quality commit messages for openSUSE and open-source contributions.

Commit messages communicate vital information between team members, and since open-source software is one big team focusing on open collaboration, it’s imperative to communicate context in these messages.

Why?

The “Why?” may be obvious to you now, but it might not be to others; especially those who might not even be involved yet with your code. Well-crafted commit messages help developers remember aspects of a previous commit and help future developers understand what changed and the purpose for the change. 

Commit messages can be considered unstructured and inconsistent, but these messages can make a world of difference with a little time and care. Think about writing commit messages in a way that is straight and to the point; kind of like a drill sergeant giving commands or instructions. Polish your boots. Clean the latrine. Do push ups. Being more specific, think about a parent telling their child what to do and for what reason. Clean the stove because the cooking oil you spilled on it can cause a fire for the next person using it.

Below are some other helpful hints for writing good commit messages.

Important bits:

• Include “Why” in the commit message in addition to “What” (Create a message that provides value)

• Don’t just link to bugtrackers, because these can become unaccessible later (“Nothing endures but change” - Heraclitus, ancient Greek philosopher)

• Bonus points for stylistic consistency

  • Capitalize first letter (Unless that first word is openSUSE)

  • Use Imperative form (Imperative form isn’t a rude form of expression; it’s detailed and provides clarity, just like the headline of this blog)

  • No trailing dot in summary

  • Limit line length (A good rule is to keep the characters use low; around 50 for the first line)

For those that are interested in more details, there is an extensive amount of helpful hints at https://cbea.ms/git-commit/.