Semantic version number management utility designed for use with GitLab CICD
Project description
VerNum
Configurable GitLab CI/CD-powered version numbering for project releases
(Similar to GitVersion)
Python module/CLI installation
The VerNum Python module is distributed as a PyPI module and can be installed like any other.
Install with system-level Python
pip3 install vernum
Install with pipx
to avoid dependency collisions
pipx install vernum
Install with a venv (depends on venv location)
.venv/bin/pip install vernum
... or install as a Poetry dev dependency
Commands
The vernum max
command
Takes a list of version numbers and based on the configued numbering scheme, returns the highest value in the list.
echo "1.4.0\n1.4.1\n1.5.0" | vernum max
The vernum next
command
Takes a single version number and, based on the configured numbering scheme and the selected increment, outputs the next version number.
echo "3.4.5" | vernum next patch
The vernum limit
command
Takes a single version number and, based on the onfigured numbering scheme and provided limits, triggers an error if the version number falls outside the limit. Only a minimum limit is currently supported (see configuration below).
Schemes
VerNum supports multiple "schemes" for version numbering.
Scheme | Description | Increments | Example |
---|---|---|---|
major |
Just a single version number | major |
4 |
minor |
Major, dot, minor | major minor |
4.2 |
patch |
Major, dot, minor, dot patch | major minor patch |
4.2.1 |
minor-alpha-beta |
Major, dot, minor, dot, and either a patch, alpha, or beta | major , minor , patch , alpha , beta |
4.3.alpha2 |
Schemes support an optional "v" before the version number for inputs, including from Git, but output the result without a "v".
The default scheme is patch
.
Details of the minor-alpha-beta scheme
The minor-alpha-beta
scheme is designed for situations where alpha and beta pre-releases apply to minor versions. But increments only go forward, and assume that new work will start with alpha1. So:
major
changes e.g. 5.6.2 to 6.0.alpha1minor
changes e.g. 5.6.2 to 5.7.alpha1beta
changes e.g. 5.7.beta3 to 5.7.beta4alpha
changes e.g. 5.7.alpha8 to 5.7.alpha9patch
changes e.g. 5.6.beta6 to 5.6.0patch
changes e.g. 5.6.2 to 5.6.3
Use with Git tags
We designed VerNum to use with Git tags, and recommend using the history of tags in the default branch as the source of truth for version numbers.
The example below demonstrates one way to use VerNum with Git tags.
git tag --list --merged HEAD | vernum max | vernum next patch > .version
git tag -a "$(cat .version)" -m "$(cat .version)"
Keep the following pointers in mind when using VerNum with Git.
- CD to the root of the project before running it
- Be on the branch that you use for releases (i.e.
master
) - Be fully up-to-date in git (i.e. merged, committed, and pushed)
Configuration and input
VerNum uses the WizLib framework for configuration and input control.
- Input to commands can come through stdin
- Alternatively, use the
vernum --input <filename>
to pull input from a file - The scheme can be selected with an environment variable
$VERNUM_SCHEME
- Alternatively, the scheme can be set in a YAML configuration file; the application will try, in order:
- A config file location designated with
vernum --config <filename>
- A config file location designated with a
$VERNUM_CONFIG
environment variable .vernum.yml
in the local directory.vernum.yml
in the user's home directory
- A config file location designated with
We recommend placing a .vernum.yml
file in the project directory and committing it to the project's Git repository, so different environments use the same scheme.
The format for the YAML file is simple (allowing for other forms of configuration in the future):
vernum:
scheme: minor
limit:
min: '4.2'
Usage (GitLab CICD)
See the ProCICD documentation for usage within GitLab CICD.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.