comver

Commit-based semantic versioning - highly configurable and tag-free.

✨ Features 🚀 Quick start 📚 Documentation 🤝 Contribute 👍 Adopters 📜 Legal

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

Why?

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.

Quick start

[!NOTE] You can jump straight into the action and check comver tutorials.

Installation

```sh

pip install comver ```

Calculate version

[!IMPORTANT] Although written in Python, comver can be used with any programming language.

If your commits follow the Conventional Commits format, run:

```sh

comver calculate ```

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

sh 23.1.3 # Output

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

Configuration

Configuration can be done either in pyproject.toml (recommended for Python-first project) or in a separate .comver.toml file (recommended for non-python projects):

[!TIP] See suggested configuration examples here

Integrations

[!NOTE] You can use comver with uv by selecting the appropriate build backend, such as hatchling.

To integrate comver with pdm or hatch add the following to your pyproject.toml:

[!TIP] See more in the documentation

Verification

To verify that a version was produced from the same Git tree and configuration, first use the calculate command with additional flags:

sh comver calculate --sha --checksum

This outputs three space-separated values:

sh <VERSION> <SHA> <CHECKSUM>

[!TIP] Append --format=json for machine-friendly output

Before the next release provide these values to the comver verify to ensure the version was previously generated from the same codebase and config:

sh comver verify <VERSION> <SHA> <CHECKSUM>

If inconsistencies are found, you'll receive feedback, for example:

Provided checksum and the checksum of configuration do not match.

[!TIP] Explore verification workflows in the tutorials

Contribute

We welcome your contributions! Start here:

• Code of Conduct
• Contributing Guide
• Roadmap
• Changelog
• Report security vulnerabilities
• Open an Issue

Legal

• This project is licensed under the Apache 2.0 License - see the LICENSE file for details.
• This project is copyrighted by open-nudge - the appropriate copyright notice is included in each file.