Tired of keeping track of whether your code changes warrant a minor or major version increment? Too busy to keep a neat and tidy changelog? Try using commitizen, a command-line utility that "forces" you to write commit messages following the Conventional commits standard (or a different, user-defined format). Once configured, commitizen will bump the semantic versioning of your code automatically based on your commits, and update your changelog.
Configuration
Commitizen is configured in five simple steps. First, you need to install commitizen:
pip install commitizenSecond, add a reference to your code’s current version number to your __init__.py file, or add a separate __version__.py file as shown below:
Third, update your .pre-commit-config.yaml to include a pre-commit hook for commitizen (if you’re unfamiliar with pre-commit hooks, check out my earlier blog post on using pre-commit hooks for improving code style):
Fourth, update your pyproject.toml file to include commitizen, which references the current version of your code as well as other locations in your code where the version needs to be updated upon a commit (such as your setup.py file):
Finally, run pre-commit install --hook-type commit-msg to set up the commitizen pre-commit hook.
Using commitizen in your git workflow
Now that we’ve installed and configured commitizen, let’s take a look at its use in your git workflow.
Let’s assume you’ve checked out a new (feature) branch and you’ve made some changes that you’d like to commit. Instead of using the conventional git commit '<commit-message>' command after adding (un)tracked files, we use the commitizen commit command (or cz c in short). Using this command will prompt a bunch of options:
Use the selection menu to classify the kinds of changes you’ve made (e.g. a bug fix, or a new feature), and add a commit message when prompted to do so. This will prefix the commit message with the selected code change classification (e.g. feat or fix). For example, if you’ve added a new feature, the commitizen-generated commit message may look as follows:
doc: update READMEAfter you’ve made your commit and pushed your branch, registered a PR, and merged to master (or "main"), check out the master branch and run:
cz bump --check-consistency --changelogThis will check the consistency of the versions in your commitizen configuration (and code), and generate or update a changelog (see here for an example of a commitizen-based changelog). Subsequently, run the following commands to update the changelog and version references on your branch, and push the new version tag:
git push
git push --tagsAnd that’s it – now you’re all set up for automated version and changelog bumps for your Python project based on your commit history. Thanks for reading!
_P.s. if this all went a bit too fast, have a look at this repo I set up for a different blog post, where I’ve used commitizen for versioning._
If you liked this article, here are some other articles you may enjoy:
How to improve your Python code style with pre-commit hooks
Automating Unit Tests in Python with Hypothesis
Simplify your Python Code: Automating Code Complexity Analysis with Wily
Please read this disclaimer carefully before relying on any of the content in my articles on Medium.com.
