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.commitizen example 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 the commitizen pre-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

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.

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, 

Example CZ commits

.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.

SemVer

.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.

Reference:

Aritra Biswas
Aritra Biswas
Senior Manager, AI Engineering

I work at the intersection of analytics, machine learning, and software engineering, with research interests in computational statistics, causal inference, simulation, and mathematical optimization.