<- BACK TO ARCHIVE
EN

Python package versioning: SemVer, Git and PEP 440

IDEAS / CODE / PROCESS *

Edited article

Last edited:

For this guide on managing Python package versions, Semantic Versioning (SemVer) will be used as the basis for versioning.

Basic concepts

The classic versioning scheme is:

MAJOR.MINOR.PATCH

bash
0.1.0

0.1.1

0.2.0

1.0.0

Each number has a meaning; from right to left it would be:

PATCH: fixes that do not break compatibility with previous versions 1.2.4 → 1.2.5

MINOR: new features compatible with everything that already exists 1.2.4 → 1.3.0

MAJOR: changes incompatible with previous versions 1.3.0 → 2.0.0

When to create a new version

A release is created when you have a project state that is considered installable, identifiable, and reusable.

Imagine you find a bug and you make different commits to fix it. When you manage to fix it and you push a change that simply fixes that small bug, then you would update the PATCH.

After that bug, you decide to add a new feature that does not affect the normal operation of the system, then we would change the MINOR version.

If you want to change the parameters of functions that are used in other repositories, making it so you must modify the repositories that depend on what you just changed, it would be considered a big change that causes incompatibility, so the MAJOR version is changed.

A frequent question is when version 1.0.0 should be released. For that, I will simply quote the SemVer website:

If your software is being used in production, it should probably already be 1.0.0. If you have a stable API on which users depend, you should be 1.0.0. If you're worried a lot about backwards compatibility, you should probably already be 1.0.0.

PEP 440 (pep440): Python package versions

In addition to the system above, Python has its own versioning system that defines how versions should be written.

Formats such as these are allowed:

bash
1.0.0

1.1.0

2.0.1

But it also allows development versions:

bash
1.2.0a1
1.2.0b1
1.2.0rc1
1.2.0

Where they represent:

bash
a -> alpha
b -> beta
rc -> release candidate
standard format -> stable release

Use these suffixes when you need to distinguish development, prerelease and stable distributions. Installers compare versions according to the Python packaging version specification. SemVer describes how changes affect compatibility; PEP 440 defines the version syntax and ordering Python tools understand.

Package version + Git tag

This practice is highly recommended: each version that is published (the code is packaged for use in other repositories) should have an equivalent Git tag associated with it.

Git tag → labels that point to a specific commit, usually relevant moments in the project.

This allows us to know which code generated package v0.3.0.

To create a Git tag, the first thing is to have the commit done and pushed to main/master; afterwards you only need to run the following command:

bash
git tag -a v0.2.0 -m "COMMIT_NAME"

That will create:

bash
commit abc123
    ↑
  v0.2.0

And lastly you have to push the tag to Forgejo with:

bash
git push origin v0.2.0

Normally a git push does not automatically push tags, so git push origin v0.2.0 is used explicitly.

How to specify dependencies

You can pin an exact version such as: "example-package==0.3.1"

But this format will not automatically receive bug fixes.

So it is much more recommended to use MINOR version ranges, e.g.: "example-package>=0.3.1,<0.4"

Changelog

Since the packages we use are private packages, it is recommended to have a log of the changes that each version implements. It is very useful for people who want to add a package as a dependency; with this log, doubts such as “Can I update from 0.2.1 to 0.3.0?” will be cleared up, and similar questions.

A possible format for this log would be:

bash
# Changelog

## 0.3.0

### Added

- Added NRLMSISE atmospheric model.
- Added configurable solar activity.

### Changed

- Improved atmospheric interpolation.

### Fixed

- Fixed density calculation above 500 km.

## 0.2.1

### Fixed

- Fixed invalid temperature interpolation.

## 0.2.0

### Added

- Initial atmospheric interpolation support.

Keep in mind

  1. Software that uses semantic versioning MUST declare a public API. This API can be declared in the code itself or exist exclusively in the documentation. Whatever the method, it MUST be precise and complete.
  2. Once a package version has been published, the contents of that version MUST NOT be modified. Any modification MUST be published as a new version.
  3. Version 1.0.0 defines the public API. How the version number is incremented after this release depends on this public API and how it changes.

Sources

semver

PEP 440

To manage your environment and lock dependencies, see uv as a Python project manager. My Forgejo CI/CD and package publishing guide connects Git tags with building and uploading a release.