Formatting commit messages and writing a proper description that reflects the code changes can be tiresome but is essential for a growing project. When more than one developer is working on the same code-base, you will experience a lot of back and forth, with code getting dumped, reverted, or staying in the repository for a while.

In distributed teams, this may happen due to not following the same pattern. Conventions are subjective, always. But you can try to bring things to a common ground where everyone agrees upon it.

Here are a few good examples that Datum Brain follows to format a commit message.

Title Line

Commits can be too long or too short, depending on the work done in the code against that commit. A commit message may or may not have a description if it’s not much work.

The commit title line should always be summarized information less than 50 characters.

Why 50 Characters?

50 characters is the limit some git applications have on their default zoomed page view. So it is better to keep it short to 50 characters rather than seeing ellipses that cut off the title.

Let’s assume MGP-1 was about adding a few lines to the .gitignore file.

It is not much work, so maybe we can represent it in one title line without a body.

Bad Examples

“Frustrated at 2AM.”

done

“Too fast, trying out something that might work.”

smthing

“Stubborn as hell.”

ds store added in git ignore

“Won’t follow the system. Rebellion.”

adding `.DS_Store` in .gitignore file

Good Examples

“Contributing to the code.”

Adding `.DS_Store` in .gitignore File

“Playing my part.”

.DS_Store Added in .gitignore

Summary

Commit titles should have the following properties:

  • Title case such as “This Sentence is Having Title Case”
  • 50 characters or fewer

Description

Commit description is an important part of commit history and helps a lot to reviewers of pull requests who are analyzing your code against the task (probably) they assigned to you.

For the sake of helping them to understand (and reducing questions), you should make it a little more subtle.

Bad Examples

“Too long & redundant.”

Scaffolded & Added Configuration Files

Added configuration files and scaffolded the project, the HOCON boilerplate is all removed from the configuration files. Then moved towards working on defining project architecture for rest of the code, folders and files - basically.

Good examples

“Perfect. Bullet-ed.”

Scaffolded & Added Configuration Files

* Configuration segregated
* Added basic project structure
* Added README.md for instructions to run

Summary

Commit descriptions should have the following properties:

  • Bullet-ed
  • Each line not ending with a dot
  • Each line telling something that is not already mentioned in lines above
  • First letter capital