4.5.1. Commit Messages / Change Messages

A stitch in time saves nine. This proverb is equally applicable here. If you put a good commit message to describe the changes now, it will help you really well in future. If you take any shortcuts now, it’s going to make things complicated for you in future.

Before we list down what good messages look like, let’s list some bad messages.

4.5.1.1. Bad Messages

  • Work In Progress

  • My updates

  • WIP

  • Updated book

  • Updated images

4.5.1.2. Git Convention

Recommended convention in Git is:

Subject of max 50 characters

Detailed description.  One empty line between the subject and
detailed description. Maximum 72 characters.

Further details if needed, still maximum 72 characters wide.

- May have bulleted list
- And other items

References to PRs/Ticket IDs that are relevant for this change.

Although this is a convention for Git, it can easily be applied to other configuration management systems as well.

The subject recommends these conventions:

  • Maximum 50 words

  • Title Case

  • No terminating “.” at the end

  • Focus on Action not Status

The reason to do it this way is that you can quickly glance through one line history of the changes when you refer them in future.

Note

Problem Report / Incident Report / Ticket IDs in the message

It is a very important practice to ensure that you mention the Problem Report / Incident Report / Ticket IDs in the message to cross-reference changes related to given issue in future.