Making great commit messages with Commitizen

Commitizen, cz, is a tool used by the CHIME FRB Group to create standardised messages when committing changes to git. In addition to this, it can also bump the version of the repo automatically based on the commit history and will keep track of changes in a CHANGELOG.

Installing Commitizen

Commitizen can be installed by simply entering the following command:

pip install commitizen

Committing with Commitizen

Before we can commit using Commitizen, we need to make some changes in the repository. Add the python file below to your repository:

plot_sin.py

import numpy as np
import matplotlib.pyplot as plt


x = np.linspace(0, 4 * np.pi, 100)
y = np.sin(x)

plt.figure()
plt.plot(x,y)
plt.title("y = sin(x)")
plt.show()

Now, to commit changes using Commitizen, run this command in your terminal:

Format

cz commit

or

cz c

Commitizen will display a series of prompts for you to answer, from which it will formulate your commit message.

Result

So let's answer these prompts for the changes that we made to plot_sin.py, pressing enter after each one.

1. The type of change that we made is "feat: A new feature", so use the arrow keys to move down and select it.
2. For the next question, we only edited one file so enter its name, plot_sin.py.
3. Next, describe the changes that you made to this file, I'll let you decide what to answer for that one.
4. The following prompt is a place to add extra information if you were unable to fit everything that you wanted to say above.
5. Did these changes break anything? No.
6. Lastly, we don't need to write any footer info, so press enter one last time.

Congratulations!! You've just made your first commit with Commitizen :)

Bump

Commitizen can also keep track of versioning for your repository. Versioning is important as it allows users to know when breaking changes have been made to the code. This way they know that they'll need to have more time to iron-out any issues arising from the new changes. To automatically bump up the version based on the commits that have been made, run:

Format

cz bump

The version format follows semantic versioning = MAJOR.MINOR.PATCH.

Increment	Description	Conventional commit map
MAJOR	Breaking changes introduced	BREAKING CHANGE
MINOR	New features added	feat
PATCH	Fixes	fix + everything else

A changelog can be generated along with the new version when bumping by appending the flag --changelog or -ch.

Format

cz bump --changelog

or

cz bump -ch

However, bump requires a config file, and so we will return to practice this at a later stage.

Changelog

A changelog can be automatically generated using all commit messages that follow the Commitizen format. This is why it is important to write well-formatted commit messages! A changelog does what it says on the tin, it keeps a log of all changes that have been made between versions. To create a changelog with Commitizen, simply use this command:

Format

cz changelog

or

cz ch

The format of the changelog is:

# <version> (<date>)

## <change_type>

- **<scope>**: <message>

Where change_type, scope, and message are taken from the git commit message and version and date are taken from the tags.

Go ahead and run the command to generate a changelog in your repository. If you look inside the new CHANGELOG.md file you should see something like this:

## Unreleased

### Feat

- **plot_sin.py**: plot sin wave

Next step

If you are now able to confidently write commit messages with Commitizen, then you are ready to move on to learn about Pre-Commit.