Ahmad Salah
Ahmad Salah

Follow

Ahmad Salah

Follow

Write better commit messages!

Ahmad Salah's photo
Ahmad Salah
·Sep 10, 2021·

2 min read

Write better commit messages!
Play this article

Table of contents

  • Rethinking the Value of Commit MessagesWhy?
  • How to write a better commit message?
  • keep the message short
  • Referencing the issue
  • Keep the details for the PR

Rethinking the Value of Commit MessagesWhy?

The perception that commit messages are mostly useless may stem from a misguided view of their purpose. While it's true that verbose or redundant messages can clutter the commit history and distract from the code changes themselves, a concise and informative message can serve as a valuable breadcrumb trail for collaborators, reviewers, and future maintainers. Such a message can convey the intent, scope, and impact of the changes in a nutshell, provide context for the changes, and facilitate the tracking of issues and bugs. Therefore, rather than dismissing commit messages altogether, we should aim to refine our writing skills and follow some guidelines to make them truly helpful.

How to write a better commit message?

Commit messages can be a hassle for many developers, often lengthy and unread. To avoid this issue, one should focus on declaring their intent in as few words as possible. This can be done by simply stating whether it is a fix, feature, enhancement, or refactor. For instance, one can use the enhancement flag for developer-related features such as adding linting, enhancing CI/CD, introducing a tool, documentation, and tests.

keep the message short

It is important to keep the message short and concise, preferably in 10 words or less. This can be achieved by using verbs in the past tense, which makes more sense and adds clarity to the message. For example, one can write "Renamed class A to B" instead of "Rename class A to B".

Referencing the issue

Another crucial aspect of committing is referencing the issue that led to the changes. This provides the necessary context for the changes and makes it easier for developers, project managers, and quality controllers to follow the conversation. By using the "ref #" feature, which refers to the commit and adding a comment to the original issue, the commit message can be linked to the conversation.

Keep the details for the PR

While adding details to the commit message is not necessary, they should be included in pull requests. Here, one can explain in detail what changes were made and why they were necessary. It is important to use bullet points and keep them short.

Emojis can also be used to add some fun to the commit messages, but it is not necessary.

In conclusion, one can improve their commit messages by keeping them short, referencing the relevant issue, and adding any necessary details in the pull requests. By following these tips, one can achieve clarity and concision in their commit messages.

 
Share this