Commit messages Happy Path

Think about those messy commits, without any pattern nor body description, that you certainly have encountered at some point of your career. Take a look at some initial commits from my blog (until March 29th, 2021) to know exaclty what I'm talking about.

I made those commits that way on purpose, in order to illustrate this whole discussion about how well-made commit messages matter, and how it can improve the project that you are working with your team.

🔬 Some research were made
I asked some friends about what kind of commit message pattern they use with the project they are currently working with. All but two answers were "there's no pattern at all".

When we talk about commit descriptions, we mean easier maintainability. If this kind of topic is relevant in any kind of way for your team, you shouldn't leave a good commit message out of it.

I also believe that people who don't care about well made commit messages are the same people who don't use commands like git log and git rebase that much. But is good to know that git can also be a documentation tool, and by that, a good commit really improves it's efficiency.

Two pieces of gold about commits

It's common to follow up some rules when building a commit, like the addition of some hash that refers to some issue tracker or even the usage of Karma pattern to better organize scope. Those next tips changed completely my perspective about how to delivery reliable commits:

1. Use imperative mode over titles

All git features already uses imperative messages, like git revert or git merge for example, so it's good to keep that in mind. This also will benefit the git log command.

A simple reminder to always track that rule is to think about the following sentence, whenever a title should be built:

"When applied, this commit will <title message>"

For example:

• When applied, this commit will update header components
• When applied, this commit will add footer component

2. Follow the "why", forget about the "how"

Good codebases are very self-explained, good commits should be as well. Try to tell stories with your commit descriptions instead of just point out the thing that you did, for example:

Don't follow this path:

This one is good shit:

• feat follows the Karma pattern
• (header) is the scope of what is being the topic of this commit
• Imperative title is presented
• There's a good explained description
• If there's any issue tracker integrated to the project, refer to it at the end

✨ A little bit more details
Besides Karma, there's also another good specs resource, presented at Conventional Commits, it's worth to take a look!

More good pratices

It's common to also find those additional rules whenever we have well-made commits as a subject:

1. Capitalize the title
2. Don't use period at the end of the title
3. Jump one line between the title and description
4. Limit the title to 50 characters
5. Limit the description to 72 characters per line

In addition to the last two tips presented before, we get the famous "7 rules of a great commit message", yay!

If your team doesn't care about all that jazz, bring that up for them! It's something that can be good for everybody.

See you next time! 👋🏾