Introduction

Git is a version control tool that enables tracking changes in source files and other related files. Git has grown in popularity with the emergence of distributed git-based source control platforms such as Github , GitLab , and Bitbucket

We shall cover basic usage and setting up of git in a future article.

In this article, we’ll look at ways to write good commit messages that are meaningful to humans.

How to craft meaningful messages

It’s better to have a message that summarizes what changes to be made to make it easier for other developers and project maintainers on the team to follow along with the changes on a given branch and related commit activities.

Conventions exist that can be used to enforce certain commit messages structure, conventional-commit-types provides a good summary of structuring meaningful and consistent commit messages.

The convention can be summarized to give us a good summary of how we can craft meaningful commit messages:

The convention summarizes types of commits/changes into the following:

  1. feat: Adding a new feature
  2. fix: Fixing a regression/bug
  3. docs: Documentation only changes
  4. refactor: A code change that neither fixes a bug nor adds a feature
  5. style: A change that affects the style of code(indentation, formatting, semi-colons)
  6. perf: A code change that improves performance
  7. test: Adding missing tests or correcting existing tests
  8. build: Changes that affect a build system
  9. ci: Changes to CI configuration files and scripts
  10. chore: Changes that do not affect source or test files
  11. revert: Change that reverts a previous commit

Say one fixed a regression that they introduced working on a new feature, a typical commit message for such change would go like this: fix: fix regression introduced in #2, add isLocalhost check to useCallback dependencies etc.

With the above convention, our message follows this format <summary>: <a brief description of changes made>. Say one added new test cases for existing functionalities, a typical commit message for this kind of change would be: test: Add test for existent OpenseaMarketPlace class methodgetUser``

Following the above convention, the following (hypothetical) commit messages to make it easier to commit follow any commit activity for a given branch:

  • commit message one: feat: add ToggleButton for dark/light theme
  • commit message two: test: add test coverage for ToggleButton component
  • commit message three: `test: add more tests for edge cases
  • commit message four: refactor: change the background color for ToggleButton to #000

From the structure, one can deduce, what type of change and the summary of this type of change in one line.

Meaningless commit messages 👎👎

Taking time to craft meaningful messages should be a habit. It shows that one cares and it helps project maintainers and other contributors by giving them an easy time reviewing changes. Look at the following hypothetical commit message:

  • commit message: fix loaderModal

or worse still:

  • commit message: fixes #4 and #8

One commit with such a message might not do any harm, enter multiple commits:

  • commit message one: add ToggleButton
  • commit message two: fix loaderModal
  • commit message three: fix TxToast component
  • commit message four: add tests
  • commit message five: add more tests
  • commit message six: change the background color for ToggleButton

For someone reviewing the changes, it becomes really hard to follow what’s happening on that branch and would require a lot of head-scratching to find out which can be time-consuming and annoying. The commit activity looks more “noisier” and cluttered.

Summary

Good commit messages are good and helpful for both maintainers and contributors due to the standard and conventions in play.

Conventions are not “rules” written in stone but having conventions enforces super beneficial consistency across the repository. Better to have a convention in place than no convention and inconsistency across the repository.