3 tools to make the commits in your repository more professional

Show professionalism and maturity through your repositories applying good practices to write commit messages

A management version repository that has an organized history of changes and good commit messages shows maturity and professionalism. This organization begins writing commit messages that make clear the intention behind the change made and also has a guideline followed by all the team.

In this article, we will see how you can structure the commit messages in your repository and apply some good practices that can be shared by all the team. We will make use of tree tools to help us to write good commit messages, validate, and make sure that all the rules are being followed.

The following good practice and tools can be applied to Git repositories no matter what kind of programming language this repository keeps track of.

The art of writing good commit messages

Writing good commit messages can be considered an art. And mastering this art takes time and practice. When making a commit of code we can see it as a picture of our work. If the code is a picture then the commit message is a subtitle that puts a description of our work.

When it is time to commit, the developer sees himself free to write a description of his work. Each one has a way to write and in a team, this can lead us to many problems. Without a guideline with some rules to follow and structure the message, we can end with a repository to just stock code without taking all the advantages the tool provides. Later, when we need to go back and check the history to find something, all commit messages can be a mess and make no sense. 

The article “How to Write a Git Commit Message” is one of these texts to keep bookmarked. Although there is no main guideline to be followed, we can take some good rules like:

• Write the subject using the imperative mood
• Limit the number of characters of the subject
• Do not end a subject with a period punctuation
• Use the body message to describe the why vs how
• Limit the number of characters of the body and wrap the text
• Separate the subject and body with a blank line

Following rules like these without a tool to help is a pain. We will show how you can write commit messages always with the same structure and better describe the intention of your commit.

Tree tools will be used. These tools were written in javascript and despite the development language and the use of Node.js to make it work, the repository can hold code in any language. 

The tools are the following:

Pre-requirements

As said before, we will use the tools, commitlint, husky, and commitizen. All of them have as a pre-requirement the node.js and Git installed. Let’s see how you can install the node using a Linux machine. If you are using Windows you can follow this tutorial.

Installing the nvm and node.js

The nvm is version manager for node.js. Let’s install it first and use it to install the node.js. If you use the bash shell, open the terminal and run the following command:

$ curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.3/install.sh | bash

Close and open the terminal again and run the following command to see if the nvm is installed with success:

$ nvm --version
0.35.3

If you zsh as your terminal will be necessary some additional steps to finish the installation.

Now, let’s install node.js using the nvm. In the date of this article, the current version is 12 (12.16.2).

$ nvm install node 12

Check if the node installation is working:

$ node -v
V12.16.2

Also, check if the package manager npm is working:

$ npm --version
6.14.4

Configuring your repository

The steps to configure your repository should be done only once and preferably before the developers start to make commits. After this configuration, all developers can make a clone of the repository, and before starting to work they need to execute the command “nvm install” into the root folder. If the repository is already configured the following steps should not be followed. 

After installing the node.js let’s install and configure other tools in the Git repository. To use the tools Commitlint, Husky and Commitizen you need first initialize it with the “git init” command, however, if you use remote version management like GitHub or Bitbucket you can create the repository remotely and clone it in your local machine. Just in case you want to follow this tutorial in your local machine with a fresh repository run the following command.

$ mkdir <nome-do-repositorio>
$ cd <nome-do-repositorio>
$ git init

Let’s create or change the file .gitignore to ignore the node_modules folder. This folder will store the tools.

$ echo “node_modules/” >> .gitignore

Before start, the installation of the tools lets create a package.json file. It is responsible to store the dependencies and configuration of the tools. Run the following command and a new file package.json will be created in the current folder.

$ npm init -y

Now, let’s install the commitlint that will be responsible to validate your commit message following a set of rules. Run the following command and the tool will be installed within the node_modules folder and a new entry will be added into the package.json file.

$ npm install @commitlint/cli --save-dev

It’s time to install the config-conventional. It is the set of rules that will be followed by our commit messages. Run the following command and the files will be installed within the node_modules folder and a new entry will be added into the package.json file.

$ npm install @commitlint/config-conventional --save-dev

In this step, it is necessary to configure the commitlint to use the validation rules from config-conventional. So, let’s create the commitlint.config.js file with the following command:

echo "module.exports = {extends: ['@commitlint/config-conventional']}" > commitlint.config.js

The next too to be installed is the Husky. It is responsible to receive events from the Git and trigger the commitlint to validate the commit message. Run the following command.

$ npm install husky --save-dev

For configuring what are the events where the Husky will listen add the following text into the package.json file.

WARNING: If in the code below you find the symbol && replace it by && some browser renders the code wrong.

"husky": {
   "hooks": {
        "commit-msg": "commitlint -E HUSKY_GIT_PARAMS",
        "prepare-commit-msg": "exec < /dev/tty && git cz --hook || true"
        }
  },

According to the git documentation, during the event “commit-msg” it is possible to format or validate the message. The vent “prepare-commit-msg” allows us to execute commands before the commit editor is opened. Are in these events that commitzen will work and guide the user to write good commit messages.   

To install the commitizen run the following command:

$ npm install commitizen --save-dev

We also need to configure it to work following the validation rules form the config-conventions. Run the following command:

$ ./node_modules/.bin/commitizen init cz-conventional-changelog --save-dev --save-exact

We are done! Now we have configured the git repository and we can test if everything is working as expected.

Making commits in a configured repository

Add all the changes to the management version system and run the commit command:

$ git add .
$ git commit

Now, you will be guided to build your commit message. It’s also a good practice don’t mix more than one change into a single commit, the commit must be atomic and do not put the code into the repository into a state of failure with compile errors or tests broken. 

Choose the type of change that is being made. For this example let’s choose “feat”:

ᐳ git commit
husky > prepare-commit-msg (node v12.16.2)
cz-cli@4.0.4, cz-conventional-changelog@3.1.0

? Select the type of change that you're committing: (Use arrow keys)
❯ feat:     A new feature 
  fix:      A bug fix 
  docs:     Documentation only changes 
  style:    Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc) 
  refactor: A code change that neither fixes a bug nor adds a feature 
  perf:     A code change that improves performance 
  test:     Adding missing tests or correcting existing tests 
(Move up and down to reveal more choices)

If your repository has more than one module you can specify the scope of the change. Let’s skip this step, just press enter key:

? Select the type of change that you're committing: feat:     A new feature
? What is the scope of this change (e.g. component or file name): (press enter to skip) 

Write the subject. Remember that it’s a good practice to write the subject using the imperative mood.

? Select the type of change that you're committing: feat:     A new feature
? 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 66 chars):
 (55) configure the repository for commit message conventions

Write the description to tell why the change was made.

? Provide a longer description of the change: (press enter to skip)
 Specified a commit message convention for better track the changes in this repository through 
the use of the tools commitizen, commitlint and husky.

In the next two steps let’s specify that the changes do not introduce breaking changes and it is not related to any open issue.

? Are there any breaking changes? (y/N) N
? Does this change affect any open issues? (y/N) N

Your default text editor will be opened with a message preview that will be committed. Close the editor and the commit will be made.

[master 47bb6b3] feat: configure the repository for commit message conventions
 1 file changed, 0 insertions(+), 0 deletions(-)
 create mode 100644 dummy.txt

ᐳ git log
commit 47bb6b3f6f1b37776ce365c7589345ffe3c4ecbd (HEAD -> master)
Author: Eduardo Costa 
Date:   Mon Apr 27 13:20:38 2020 -0300

    feat: configure the repository for commit message conventions
    
    Specified a commit message convention for better track the changes in this repository through the
    use of the tools commitizen, commitlint and husky.

Conclusion

The commit messages are a very important way to register the changes made into the repository and writing a good message is not an easy task. Using some tips, like to write the title in an imperative mood and the message body describing why the source code changed help us to create good messages. 

Standard commit messages are evidence of maturity and professionalism and improve the reliability of the history of changes into the repository, it also helps us to undo some changes and track the cause of issues.

Using some automation tools like Commitlint, Commitizen and Husky, ensure that rules will not be broken and help developers to write good commit messages.

What next

What next

Besides the shown benefits, standardized commit messages are a requirement to automate the semantic versioning, an important topic of software configuration management. There are some tools like semantic release, that can automate this process and besides that, to create a version tag in the branch and also generate the changelog. This is a good topic to start studying and write a new article.

This article was written by Tulio Polachini e Edu Costa feel free to leave a comment if you have some question.