comver¶

Features¶

comver is a tool for calculating semantic versioning ⧉ of your project using only commit messages - no tags required!

Separation of concerns: versioning focuses on technical aspects, not marketing. You can now use tags solely for communication.
Highly configurable: include only relevant commits by filtering via message, author, email, or even commit path.
Immutable: version is calculated directly from the commit history. Tags can now be used more meaningfully (e.g., to mark a major milestone or release).
Batteries-included: integrate with pdm ⧉, Hatch ⧉ or uv ⧉.
Verifiable: verify that a specific version was generated from a given commit chain - more resistant to tampering like dependency substitution attacks ⧉

Semantic versioning based on Git tags has a few limitations:

Teams may avoid bumping the major version due to the perceived weight of the change. Double versioning scheme ⧉; one version for technical changes, another for public releases is a viable mitigation.
Tag creation by bots (e.g. during automated releases) lead to problems with branch protection (see here ⧉).
Not all commits are relevant for release versions (e.g., CI changes, bot updates, or tooling config), yet many schemes count them in. With filtering, comver can exclude such noise.
Tags are mutable by default and can be re-pointed. By calculating the version based on commits, and combining it with the commit sha and a config checksum, you get verifiable and reproducible results.

Note

You can jump straight into the action and check comver tutorials ⧉.

> pip install comver

Important

Although written in Python, comver can be used with any programming language.

If your commits follow the Conventional Commits format, run:

> comver calculate

This will output a version string in the MAJOR.MINOR.PATCH format:

23.1.3 # Output

Important

You can use plugins ⧉ to integrate this versioning scheme with pdm ⧉ or hatch ⧉. More below!