comver 0.2.0

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

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

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

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

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):

pyproject.toml	.comver.toml
[tool.comver] # Only commits to these paths are considered path_includes = [ "src/*", "pyproject.toml", ] # Commits done by GitHub Actions bot are discarded author_name_excludes = [ "github-actions[bot]", ]	# No [tool.comver] needed here # Source only commits considered path_includes = [ "src/*", ] # Commits messages with [no version] are discarded message_excludes = [ ".*\[no version\].*", ".*\[skipversion\].*", ]

[!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:

PDM	Hatch
# Register comver for the build process [build-system] build-backend = "pdm.backend" requires = [ "pdm-backend", "comver>=0.1.0", ] # Setup versioning for PDM [tool.pdm.version] source = "call" getter = "comver.plugin:pdm" # Comver-specific settings [tool.comver] ...	# Register comver for the build process [build-system] build-backend = "hatchling.build" requires = [ "comver>=0.1.0", "hatchling", ] # Setup versioning for Hatchling [tool.hatch.version] source = "comver" # Comver-specific settings [tool.comver] ...

[!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:

comver calculate --sha --checksum

This outputs three space-separated values:

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

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.