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

Installation

> pip install comver

Calculate version

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

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

[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\].*",
]

Integrations

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

# 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]
...

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>

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.

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.