Semversioner

The easiest way to manage semantic versioning in your project and generate CHANGELOG.md file automatically.

Semversioner will provide the tooling to automate semver release process for libraries, docker images, etc.

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 next-release 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.

Install

$ pip install semversioner

Usage

Bumping the version

In your local environment your will use the CLI to create the different changeset files that will be committed with your code. For example:

$ semversioner add-change --type patch --description "Fix security vulnerability with authentication."

Then, in your CI/CD tool you will need to release (generating automatically version number) and creating the the changelog file.

$ semversioner release

Generating Changelog

As a part of your CI/CD workflow, you will be able to generate the changelog file with all changes.

$ semversioner changelog > CHANGELOG.md

You can customize the changelog by creating a template and passing it as parameter to the command. For example:

$ semversioner changelog --template .semversioner/config/template.j2

The template is using Jinja2, a templating language for Python. For example:

# Changelog
{% for release in releases %}

## {{ release.version }}

{% for change in release.changes %}
- {{ change.type }}: {{ change.description }}
{% endfor %}
{% endfor %}

You can filter the changelog by only showing changes for a specific version:

$ semversioner changelog --version "1.0.0"

Alternatively, you can use the following command to filter changes by the last released version:

$ semversioner changelog --version $(semversioner current-version)

Getting 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 next version based on the current change set. This will not change any files on disk, and they are as such preserved for any future release.

$ semversioner next-version

License

Made with ♥ by Raul Gomis <https://twitter.com/rgomis>.

Changelog

Note: version releases in the 0.x.y range may introduce breaking changes.

1.4.0

minor: Add support for storing release datetime in order to display it in the changelog.
patch: All tests are now able to be run on Windows
patch: Fix: bug showing incorrect error using release command with no changesets created.

1.3.0

minor: Add CLI command to detect missing changeset files before merging to the destination branch.
minor: Add exception handling support to use Semversioner as a library.
patch: Fix next-version error command color.

1.2.0

minor: Added command next-version, to compute the version of the next release, without actually performing the release

1.1.0

minor: Expose models to use semversioner as a library.
minor: Use models for better encapsulation and code refactoring.

1.0.0

major: Drop support for Python 3.6.
minor: Add type hinting.
minor: Bump click dependency to 8.0.3.
minor: Bump jinja2 dependency to 3.0.3.
patch: Add Python 3.10 testing in the CI/CD process.
patch: Bump importlib_resources dependency to 5.4.0.
patch: Bump pytest dependency to 6.2.5.
patch: Bump twine dependency to 3.7.1.
patch: Bump wheel dependency to 0.37.0.
patch: Remove unnecessary dependency: colorama.
patch: Rename semversioner directory to .semversioner.

0.13.0

minor: Add support for custom changelog template
patch: Fix security vulnerability with jinja2 CVE-2020-28493

0.12.0

minor: Improved performance by supporting multiple changeset files per second
minor: Status command now sorts unreleased changes by type and description in order to display consistent results
patch: Internal code refactor to improve code readability and maintanability

0.11.0

minor: Add '--version' filter to the 'changelog' command to display the changelog only for a specific version

0.10.0

minor: Add new 'status' command to display the state of the working directory and unreleased changes
patch: Fix build and deployment configuration
patch: Refactor method names and code for better code readability and testability

0.9.0

minor: Deprecated .changes directory in favour of .semversioner directory
patch: Internal refactor to improve code quality and test coverage

0.8.1

patch: Fix installer error when referencing to LICENSE file

0.8.0

minor: Enabled autocompletion by default

0.7.1

patch: Improve docs for open source

0.7.0

minor: Fail with error code when no changes are provided in the release command

0.6.16

patch: Fix bug: add require module in setup.py

0.6.15

patch: Fix packaging for LICENSE
patch: Improve README.md documentation
patch: Use jinja2 template engine internally to generate the changelog

0.6.14

patch: Update docs

0.6.13

patch: Fix README.md

0.6.12

patch: Fix long description content type

0.6.11

patch: Add README.md file

0.6.10

patch: Fix code consistency

0.6.9

patch: Fix packaging

0.6.8

patch: Tag the repository when releasing

0.6.7

patch: Fix tests and improve coverage

0.6.6

minor: Initial version

Metadata

Release files for semversioner 1.4.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for semversioner 1.4.0
File	Size	Uploaded
semversioner-1.4.0.tar.gz	11.6 kB	Dec 3, 2022	Details

Built distribution (wheel)

Table of built distributions (wheels) for semversioner 1.4.0
File	Interpreter	ABI	Platform	Reset
semversioner-1.4.0-py2.py3-none-any.whl 11.8 kB Dec 3, 2022	Python 2, Python 3	none	any	Details

Total release size: 23.4 kB

Release files / semversioner-1.4.0.tar.gz

Download URL	semversioner-1.4.0.tar.gz
Size	11.6 kB
Tags	Source
SHA-256 checksum How to use checksums	`ac6a47e3f6d878f2b68bb858ef69f8a49d2ef972b4b8ef2ee0a4d2f89de35ee5`
BLAKE2b-256 checksum How to use checksums	`afefe950c133656848a293dde22d6b9276d61d835ad21a575a9f59026856c75b`
Upload date	Dec 3, 2022
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/3.7.1 importlib_metadata/4.2.0 pkginfo/1.9.2 requests/2.28.1 requests-toolbelt/0.10.1 tqdm/4.64.1 CPython/3.7.15`

Release files / semversioner-1.4.0-py2.py3-none-any.whl

Download URL	semversioner-1.4.0-py2.py3-none-any.whl
Size	11.8 kB
Tags	Python 2 Python 3
SHA-256 checksum How to use checksums	`1c33f5e5332fcb95fe578e137359d8a3a7dadd4260e5128039895c319862b443`
BLAKE2b-256 checksum How to use checksums	`f93475225ccbddbae291335da79a2fd177b73f461b7b3ca3d2b177c29bab60ae`
Upload date	Dec 3, 2022
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/3.7.1 importlib_metadata/4.2.0 pkginfo/1.9.2 requests/2.28.1 requests-toolbelt/0.10.1 tqdm/4.64.1 CPython/3.7.15`