Python library version management with GitHub action + commitizen + pre-commit hook

List of tools used in this post
Here is a sample repository that shows the implementation described below.
Context & overview
Let’s assume that we are going to build a Python library called minipackage. We need to manage its version and generate a CHANGELOG.md whenever we release a new version. There are multiple ways to solve this problem. In this post, we will see how semantic versioning can help.
Project directory structure
minipackage: All the source code for the python library will live here.__init.py__: Library version, other meta data will be here. Also, we need to register any external methods we want to expose as API in the library.main.py: main module is kind of representation of any module and sub-module which will be part of the python library.
pyproject.toml: This file will have all the meta-data related to the tools which we will be using this project. In the example,tool.commitizenexample is present but there can be many more settings registered in this file related to the other tools being used in the project.README.md: self explanatory.requirements.txt: All the python dependencies required for the library..pre-commit-config.yaml: git pre-commit hooks. Here in this example we have just shown thecommitizenpre-commit hook example. But there can be many other as well.setup.py: all the library building related information will be here.
If you want to refresh some basics of python library building process checkout this link. Regarding pre-commit checkout this link.
.
├── minipackage
│ ├── __init__.py
│ ├── main.py
├── pyproject.toml
├── README.md
├── requirements.txt
├── .pre-commit-config.yaml
└── setup.py
pyproject.toml: project tools and metadata related to tools used in project
version and version_files these are the two import field which has a major impact in this workflow. make sure that version_files field points to the file which is the single source of version. We also need to ensure that we will be using the same file and variable all across the project. While start a project __version__ in __init__.py and version variable in pyproject.toml file should match.
[tool.commitizen]
name = "cz_conventional_commits"
version = "0.0.1"
version_files = [
"minipackage/__init__.py",
"pyproject.toml:version"
]
tag_format = "v$version"
bump_message = "bump: $current_version → $new_version [skip-ci]"
In this example, we use the __version__ variable throughout the project to manage the version, and the same file is listed in pyproject.toml. When we use commitizen to bump the library version, it changes this variable based on the commit message tags. It also generates a CHANGELOG.md file in the project root directory and creates a release tag.
setup.py: library build related information
In this section, notice that we use the __version__ variable from the minipackage module. We pass it to the version argument in the setup function. This ensures that the library is assigned this version when it is built.
Note that anything defined or imported in minipackage/__init__.py will be available in the minipackage module.
from setuptools import find_packages, setup
from minipackage import __version__
setup(
author="Aritra Biswas",
author_email="pandalearnstocode@gmail.com",
python_requires=">=3.8",
install_requires=requirements,
include_package_data=True,
keywords="minipackage",
name="minipackage",
packages=find_packages(include=["minipackage", "minipackage.*"]),
version=__version__,
)
source/__init__.py: main place where the version variable is being used
This will be the initial state of the init file. Later when we bump library version in the CI pipeline, this __version__ variable will change depending upon commit message tags.
__version__ = "0.0.1"
from minipackage.main import hello_world, hello_mcu, hello_dc,

.pre-commit-config.yaml : ensuring commit message format is being followed
This is not a mandatory thing but kind of a fail safe mechanism to implement conventional commit messages in our day to day workflow.
repos:
- repo: https://github.com/commitizen-tools/commitizen
rev: v2.19.0
hooks:
- id: commitizen
stages: [commit-msg]
Once this pre-commit hook is installed in a repository, it checks whether the commit message contains the required tags whenever we make a commit. To learn more, see the Conventional Commits documentation.

.github/workflows/bumpversion.yaml : GitHub action to update the version value in the respective file
For a commit message like bump: update library version. to the configured branch, this will update the library version, generate changelog and push it to the feature branch. Post that when we trigger a build, a library with the same version tag will be generated and sent to the python library repository.
name: NEW Bump version
on:
push:
branches:
- develop
jobs:
bump_version:
if: "!startsWith(github.event.head_commit.message, 'bump:')"
runs-on: ubuntu-latest
name: "Bump version and create changelog with commitizen"
steps:
- name: Check out
uses: actions/checkout@v2
with:
fetch-depth: 0
token: "${{ secrets.GITHUB_TOKEN }}"
- id: cz
name: Create bump and changelog
uses: commitizen-tools/commitizen-action@master
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
branch: develop
- name: Print Version
run: echo "Bumped to version ${{ steps.cz.outputs.version }}"
Note: This workflow may change depending upon how you want to update the library version. Here action is driven by push to develop branch but it is possible to setup this process with pull request trigger or any other trigger as well.