Semversioner
Release automation for AI-native software delivery.
Semversioner makes it easy for developers and AI coding agents to manage
semantic versioning, capture changes, and generate CHANGELOG.md files automatically.
It provides the tooling to automate releases for libraries, Docker images, microservices, and more.
This project was inspired by the way AWS manages their versioning for AWS-cli.
Semantic Versioning
The semantic versioning spec involves several possible variations, but to simplify, in Semversioner we are using the three-part version number:
<major>.<minor>.<patch>
Constructed with the following guidelines:
- Breaking backward compatibility or major features bumps the major (and resets the minor and patch).
- New additions without breaking backward compatibility bumps the minor (and resets the patch).
- Bug fixes and misc changes bumps the patch.
An example would be 1.0.0.
How it works
At any given time, the .semversioner/ directory looks like:
.semversioner
├── next-release
│ ├── minor-20181227010225.json
│ └── major-20181228010225.json
├── 1.1.0.json
├── 1.1.1.json
└── 1.1.2.json
The release process takes everything in the next-release directory and aggregates them all together in a single JSON file for that release (e.g., 1.12.0.json). This JSON file is a list of all the individual JSON files from next-release, keeping release intent explicit and reviewable whether changes are authored by people or AI agents.
Install
pip install semversioner
Usage
You can use the --help option on any command to see the available options:
semversioner --help
Adding changesets
In your local environment, you can use the CLI to create the different changeset files that will be committed with your code. This ensures that every pull request or commit contains its own self-contained change description and version bump intention.
semversioner add-change --type patch --description "Fix security vulnerability with authentication."
Allowed --type values are: major, minor, patch.
You can also add custom attributes to the changeset file that will be available later in your release template. Use the --attributes flag in key=value format (you can pass it multiple times):
semversioner add-change --type patch \
--description "My custom changelog message with attributes." \
--attributes pr_id=322 \
--attributes issue_id=123
Checking working directory status
You can check the status of your working directory to see the current version, the computed next version, and any unreleased changes:
semversioner status
Example output:
Version: 1.0.0
Next version: 1.1.0
Unreleased changes:
minor: Added new authentication feature
(use "semversioner release" to release the next version)
Enforcing changesets in CI/CD (Check)
In your CI/CD pipeline, it's often useful to enforce that a PR includes a changeset before merging. You can use the check command to verify that there are unreleased changes in the .semversioner/next-release/ directory.
semversioner check
If no changes are found, the command exits with a non-zero status code (-1) and prints an error message.
Releasing a new version
When you are ready to create a release (usually in your CI/CD tool on the main branch), you run the release command. This automatically computes the new version number based on the unreleased changes, generates a new version JSON file, and clears the next-release directory.
semversioner release
Generating the Changelog
As part of your release workflow, you can generate the changelog file with all aggregated changes.
semversioner changelog > CHANGELOG.md
Customizing the changelog template
You can customize the changelog by creating a template and passing it as a parameter to the command. For example:
semversioner changelog --template .semversioner/config/template.j2
The template uses Jinja2, a templating language for Python. A basic example:
# Changelog
{% for release in releases %}
## {{ release.version }}
{% for change in release.changes %}
- {{ change.type }}: {{ change.description }}
{% endfor %}
{% endfor %}
If you included custom attributes (e.g., pr_id, issue_id) using the add-change command, you can reference them in your template. You also have access to current_version:
# Changelog
Note: version releases in the 0.x.y range may introduce breaking changes.
# Current version: {{ current_version }}
{% for release in releases %}
## {{ release.version }}{{ ' (' + release.created_at.strftime('%Y-%m-%d') + ')' if release.created_at }}
{% for change in release.changes %}
- {{ change.type }}: {{ change.description }}{{ ' (#' + change.attributes.pr_id + ')' if change.attributes }}{{ ' (J' + change.attributes.issue_id + ')' if change.attributes }}
{% endfor %}
{% endfor %}
Filtering the changelog
You can filter the changelog by only showing changes for a specific version:
semversioner changelog --version "1.0.0"
Alternatively, you can filter changes for the last released version:
semversioner changelog --version $(semversioner current-version)
Getting the current version
You can retrieve the currently released version of your project:
semversioner current-version
Getting the next version
As part of the CI/CD workflow, sometimes you want to release dev, rc, or other pre-release packages. For this purpose, the next-version command can be issued to compute the upcoming version based on the current changeset. This will not modify any files on disk.
semversioner next-version
Global Options
--path: Specify a custom base path for your project. Defaults to the current directory. Example:semversioner --path /path/to/project release
License
Copyright (c) 2026 Raul Gomis. MIT licensed, see LICENSE file.
Made with ♥ by Raul Gomis.
1 maintainer
Release files for semversioner 3.0.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| semversioner-3.0.3.tar.gz | 13.8 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| semversioner-3.0.3-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 27.4 kB
Release files / semversioner-3.0.3.tar.gz
| Download URL | semversioner-3.0.3.tar.gz |
|---|---|
| Size | 13.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
759625e71c24fd60a3c0b8819c8c0e8cdd6602b6d4878cf33f9dd302bf763708
|
|
BLAKE2b-256 checksum How to use checksums |
1a723cfeb2091e2721f96ef7a2d53309388a576e176b6870209c282209acd7ac
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 18, 2026.
Transparency logRelease files / semversioner-3.0.3-py3-none-any.whl
| Download URL | semversioner-3.0.3-py3-none-any.whl |
|---|---|
| Size | 13.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f7739540678f7cdf79b15894a58819ed5b569ce5268ef222ae7c3db17307727f
|
|
BLAKE2b-256 checksum How to use checksums |
0c762ee3310a8f105de9adff696263eb3703b6579b6e82af7cc4077c96df5a9b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 18, 2026.
Transparency log
