Using Conventional Commit in Projects

In this post, we will explore how to use conventional commit as well as the benefits of using it in your projects. Let's get started.

What Is It?

Conventional commit is a commit message standard first proposed by the Angular team to make their commit message uniform across different developers' check-ins. This standard gives a certain structure to commit and is helpful in building tools on top of commit messages. 

This standard is applicable to any version control and any programming language. But Git version control has many tools built and is easy to adapt for Git.

What Are the Benefits?

The conventional commit message spec gives us benefits like:

1. All developers follow the same commit message format. This helps to capture all important information about the code changes being checked in.
2. It helps with the Semver versioning of software. Thus, it will become easy to determine the next version of a product based on current commits present in the master starting from the last release tag. There are some node modules available as open-source that suggest the next version.
3. It helps to auto-generate CHANGELOG.md to document release notes for each release. Since it is auto-generated, there would not be any mistake of missing any commits in release note or tiresome effort of writing CHANGELOG.
4. It helps in automating releases if version control used is in GitHub/GitLab. There are tools like semantic release, standard version, conventional-github-releaser, and automating the release.

How to Use

Conventional commit message usage does not require any tool, but using tools helps in conforming to the message spec without really remembering it. It streamlines the process of creating commit messages, checking the message, and conforming to the standard.

I have used two node modules to create a commit message and checking the format. You need to install the node globally in your machine to make use of them. Install the node from https://nodejs.org/en/.

Commitizen

This is a very popular node tool used to create a commit message. It takes you through a set of questions about commit and prepares the commit message.

Local installation:

npm install --save-dev commitizen
npx commitizen init cz-conventional-changelog --save-dev --save-exact

cz-conventional-changelog is an adapter for commitizen to format the message. 

Once these tools are installed successfully, you can use command git-cz instead of git commit to invoke this tool. You can also have it as script inside package.json for ease of use.

Example commitizen usage:

(base) C02X66GTJGH5:quartz-acutator i322094$ git-cz
cz-cli@4.0.3, cz-conventional-changelog@3.0.2

? Select the type of change that you're committing: fix:      A bug fix
? What is the scope of this change (e.g. component or file name): (press enter to skip) 
? Write a short, imperative tense description of the change (max 67 chars):
 (32) add endpoint for managing quartz
? Provide a longer description of the change: (press enter to skip)
 Added new endpoint for managing quartz.\n - New end point for managing quartz jobs\n - Implemented as spring boot autoconfigure module
? Are there any breaking changes? No
? Does this change affect any open issues? (y/N) N

You can see that in the above output, to add a multi-line description, you need to use  \n as it does not identify a key as a continuation of the description. This is a little annoying but will do the job

Commit Message Validation

 Commitizen is a helper tool to format commit message. A developer may not install it or might use UI tools like SourceTree to do the commit. Commitizen does not provide any tool for UI like SourceTree. In such cases, we would want to check for the commit message before finalizing commit instead of discouraging the use of UI tools

We would need two things to achieve this:

Commitlint

This is another node module that will help in linting commit messages.

Local installation:

npm install --save-dev @commitlint/{cli,config-conventional}
echo "module.exports = {extends: ['@commitlint/config-conventional']};" > commitlint.config.js

Usage

echo 'fix: fix rollback issue' | npx commitlint

npx commitlint < commit_message.txt

Git Hook — commit-msg

Once you have commitlint, we need to have a way to invoking it before finishing commit. The commit-msg Git hook comes in handy here. This hook gets executed after the user has entered a commit message and before finishing a commit. If this hook exits with a status other than 0, then commit fails.

Below is the content of the commit-msg script. This has to be copied to the .git/hooks directory as .git folder contents are not copied when git clone is complete.

#! /bin/sh
export PATH=/usr/local/bin:$PATH
npx commitlint < $1
status=$?
if [ $status -gt 0 ]
then
        echo "Commit message does not follow conventional commit message spec"
        echo 'Please use "git-cz" instead of "git commit" command to format commit message according to conventional commit message spec'
fi
exit $status

We could put this script in any directory at the root of the repository so that this hook is maintained in our repository. For example, we need to create directory ' githooks' at the root of the repository and place git hooks there. Once the Git clone is done, the user can manually copy this to the .git/hooks directory.

This script will stop any commits which are not according to conventional commit format. This also gets executed when a commit happens from UI tools like SourceTree.

Note: To make this script work when committing from SourceTree, we need to add /usr/local/bin to the $PATH variable, or else it will complain that the 'npx' command cannot found.

Summary

In this post, we have seen the benefits of using conventional commit and how to set up tools to help with that. We can include all of the above steps in some script like 'setup.sh,' which does node module installation and the copying of Git hooks. This will help in reducing the steps required to do so after conducting Git cloning. This is a one-time operation after the cloning of repository. I have set up all these in one of my GitHub projects. Please refer to https://github.com/sathyabodh/quartz-acutator for the complete code.