How to Use Semantic Versioning for Shared Django Apps

2021-11-06

When you are building websites with Django, there is no need to track their software versions. You can just have a stable branch in Git repository and update the production environment whenever it makes sense. However, when you create a Django app or package shared among various websites and maybe with multiple people, it is vital to keep track of the package versions.

The Benefits

Versioning allows you to identify a specific state of your package and has these benefits:

Developers can be aware of which package version works with their websites together flawlessly.
You can track which versions had which bugs or certain features when communicating with open-source communities or technical support.
In the documentation, you can clearly see which version of the software it is referring to.
When fixing bugs of a particular version, developers of the versioned package have a narrower scope of code to check at version control commits.
Just from the version number, it's clear if the upgrade will only fix the bugs or if it requires more attention to make your software compatible.
When talking to other developers about a particular package, you can clearly state what you are talking about (yes, developers talk about software versions from time to time 😅).

Semantic Versioning

The most popular versioning scheme is called semantic versioning. The version consists of three numbers separated by dots. Django framework is using it too. For example, the latest stable version at the time of writing is 3.2.9. In semantic versioning, the first number is the major version, the second is the minor version, and the third is a patch version: MAJOR.MINOR.PATCH.

MAJOR version introduces backward incompatible features.
MINOR version adds functionality that is backward compatible.
PATCH version is for backward-compatible bug fixes.

There can also be some versioning outliers for alpha, beta, release candidates rc1, rc2, etc., but we will not cover them in this post.

By convention, the package's version is saved in its myapp/__init__.py file as __version__ variable, for example:

__version__ = "0.2.4"

In addition, it is saved in setup.py, README.md, CHANGELOG.md, and probably some more files.

Changelog

When you develop a Django app or another Python package that you will share with other developers, it is also recommended to have a changelog. Usually, it's a markdown-based document with the list of features, bugs, and deprecations that were worked on between specific versions of your package.

A good changelog starts with the "Unreleased" section and is followed by sections for each version in reverse order. In each of those sections, there are lists of changes grouped into categories:

Added
Changed
Deprecated
Removed
Fixed
Security

This could be the starting template for CHANGELOG.md:

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

<!--
### Added
### Changed
### Deprecated
### Removed
### Fixed
### Security
-->

As the new version is released, it will replace the Unreleased section while creating a new Unreleased section above it. For example, this:

## [Unreleased]

### Added

- Logging the cookie consent choices in the database because of the legal requirements.

### Fixed

- Disabling the buttons while saving the Cookie Choices so that they are not triggered more than once with slow Internet connections.

would become this:

## [Unreleased]

## [v0.2.0] - 2021-10-27

### Added

- Logging the cookie consent choices in the database because of the legal requirements.

### Fixed

- Disabling the buttons while saving the Cookie Choices so that they are not triggered more than once with slow Internet connections.

To keep track of the versions manually would be pretty tedious work, with the likelihood of forgetting one or more files or mismatching the version numbers. Gladly, there is a utility tool to do that for you, which is called bump-my-version (successor of bump2version).

Using bump-my-version

Installation

Install the bump-my-version utility as an independent tool using uv:

$ uv tool install bump-my-version

or to your virtual environment the standard way with pip:

(env)$ pip install bump-my-version

Preparation

In your package's __init__.py file, set the version to 0.0.0:

__version__ = "0.0.0"

Set the version to 0.0.0 in all other files, where the version needs to be mentioned, for example, README.md and setup.py.

Then create a default pyproject.toml file for the configuration using this command:

$ bump-my-version sample-config --no-prompt --destination pyproject.toml

You will get a file with the content like this:

[tool.bumpversion]
current_version = "0.13.0"
parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)"
serialize = ["{major}.{minor}.{patch}"]
search = "{current_version}"
replace = "{new_version}"
regex = false
ignore_missing_version = false
ignore_missing_files = false
tag = false
sign_tags = false
tag_name = "v{new_version}"
tag_message = "Bump version: {current_version} → {new_version}"
allow_dirty = false
commit = false
message = "Bump version: {current_version} → {new_version}"
moveable_tags = []
commit_args = ""
setup_hooks = []
pre_commit_hooks = []
post_commit_hooks = []

We'll make two changes here:

Change the properties commit and tag to true so that the newly created versions are committed to Git and tagged there.
Add rules for version replacements in your setup.py, __init__.py, README.md, CHANGELOG.md.

The final content of the pyproject.toml will look like this:

[tool.bumpversion]
current_version = "0.13.0"
parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)"
serialize = ["{major}.{minor}.{patch}"]
search = "{current_version}"
replace = "{new_version}"
regex = false
ignore_missing_version = false
ignore_missing_files = false
tag = true
sign_tags = false
tag_name = "v{new_version}"
tag_message = "Bump version: {current_version} → {new_version}"
allow_dirty = false
commit = true
message = "Bump version: {current_version} → {new_version}"
moveable_tags = []
commit_args = ""
setup_hooks = []
pre_commit_hooks = []
post_commit_hooks = []

[[tool.bumpversion.files]]
filename = "setup.py"
search = 'version="{current_version}"'
replace = 'version="{new_version}"'

[[tool.bumpversion.files]]
filename = "myapp/__init__.py"
search = '__version__ = "{current_version}"'
replace = '__version__ = "{new_version}"'

[[tool.bumpversion.files]]
filename = "README.md"
search = 'django_myapp-{current_version}-py3-none-any.whl'
replace = 'django_myapp-{new_version}-py3-none-any.whl'

[[tool.bumpversion.files]]
filename = "CHANGELOG.md"
search = '## [Unreleased]'
replace = '''## [Unreleased]

## [v{new_version}] - {utcnow:%Y-%m-%d}'''

Replace "django_myapp" and "myapp" with your Django app there. If you have more files, mentioning the package version, make sure to have analogous version replacements in the pyproject.toml.

Commit and push your changes to the Git repository.

Usage

Every time you want to create a new version, type this in the shell:

$ bump-my-version bump patch

$ bump-my-version bump minor

$ bump-my-version bump major

followed by the command to build the package:

$ python3 setup.py sdist bdist_wheel

As mentioned before, patch is for the bug fixes, minor is for backward-compatible changes, and major is for backward-incompatible changes.

The bump-my-version bump command will use the configuration at pyproject.toml and will do these things:

It will increment the current version number depending on the parameter passed to it.
It will replace the old version with the new one in the setup.py, myapp/__init__.py, and README.md.
It will take care of correct versioning in the CHANGELOG.md.
Then, it will commit the changes and create a tag according to the pattern vMAJOR.MINOR.PATCH there.