VerNum

Version numbering for project releases

Rat icons created by Freepik - Flaticon

Warning: Breaking Changes

Starting in VerNum v4.0.0:

No longer generates a .version file - file generation is the responsibility of an outer script
Includes alpha and beta increments
Supports the --set-current option to receive the current version number from a source other than Git tags
Requires an increment - patch is no longer the default
No longer checks Git status before proceeding
No longer provides the option to automatically update the Git tag, and no longer supports the dry-run option

Default functionality

Read the Git tags in the current branch that match the pattern e.g. "v5.6.1" and pick the highest value
Increment the version number for major, minor, patch, alpha, or beta releases
Return the new version for later use

Installation

Requires Python 3 to run the command; your project can be anything.

pip3 install vernum

Usage (CLI)

Requirements:

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)

Then run the command, specifying the increment to trigger the change:

major change e.g. 5.6.2 to 6.0.0
minor change e.g. 5.6.2 to 5.7.0
patch change e.g. 5.6.2 to 5.6.3
beta change e.g. 5.7.beta3 to 5.7.beta4
alpha change e.g. 5.7.alpha8 to 5.7.alpha9
Leave it out for no change, just to view the current version

Source of truth

The default behaviour assumes that the source of truth for the current version comes from the highest valued Git tag in the current branch (based on a regular expression match) but VerNum does not actually update the Git tag. Note that a "v" at the beginning of the input version number is optional; it's not included in the output.

Alternatively, use the --set-current option to define a different current version to reference rather than a Git tag. The override is useful for:

Bootstrapping a repo that has previous versions
Using a downstream system as the source of truth for version numbers (such as an artifact repository)
Fixing errors in the Git tag history

To update the Git tag, try something like:

vernum patch
git tag -a "cat $(.version)" -m "cat $(.version)"
git push origin "cat $(.version)"

Usage (GitLab CI/CD)

VerNum is designed for use withing GitLab CI/CD, and includes a CI/CD configuration template to support the most common use cases.

Use the provided vernum.gitlab-ci.yml to use it in GitLab. Here's an example:

include:
  - project: 'vernum/vernum'
    ref: stable
    file: 'vernum.gitlab-ci.yml'

stages:
  - Build
  - Test
  - Pre-release
  - Release
  - Post-release

deliver:
    stage: Post-release
    script:
        - echo "Edit this script to deploy or distribute v$(cat .version)"

The CI/CD template will provide a set of manual jobs following the rules:

Numbered version increments (patch, minor, major) only on the default branch
Alpha and beta increments only on branches that start with next-

Usage:

Go to the pipeline view in GitLab for the project and choose the latest pipeline on the appropriate branch
Confirm the pipeline represents the commit you intend to release
Go into the "Latest version info" when it's done, and confirm that the latest version number is accurate
Click the "play" button on the appropriate release job (major, minor, alpha, etc.)
After the release job is complete play the "Increment Version" job - it will fail if played too soon
When the "Mark Release in GitLab" job is complete, go into it to confirm the new version

Release files for vernum 5.0.3

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

Source distribution (sdist)

Source distribution for vernum 5.0.3
File	Size	Uploaded
vernum-5.0.3.tar.gz	4.4 kB	Oct 5, 2023	Details

Built distribution (wheel)

Table of built distributions (wheels) for vernum 5.0.3
File	Interpreter	ABI	Platform	Reset
vernum-5.0.3-py3-none-any.whl 5.2 kB Oct 5, 2023	Python 3	none	any	Details

Total release size: 9.6 kB

Release files / vernum-5.0.3.tar.gz

Download URL	vernum-5.0.3.tar.gz
Size	4.4 kB
Tags	Source
SHA-256 checksum How to use checksums	`29b998514a73ce1b4038c4a127511a19e950355b8f4f8f2307e63c22bf12cae5`
BLAKE2b-256 checksum How to use checksums	`71a618d5ee3ae481e12b3cd5631e20b61002666fd60969bd1f3baf329d4ef4a0`
Upload date	Oct 5, 2023
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`poetry/1.6.1 CPython/3.11.6 Linux/5.4.109+`

Release files / vernum-5.0.3-py3-none-any.whl

Download URL	vernum-5.0.3-py3-none-any.whl
Size	5.2 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`d0e795bdc9aafcf375923b1b8e39446545c845172d371c3fa0ca361801f4684f`
BLAKE2b-256 checksum How to use checksums	`600c47b495f1d7b7fa9316f23ca8bad9a56c29256e8e9e71860d50759a6631bb`
Upload date	Oct 5, 2023
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`poetry/1.6.1 CPython/3.11.6 Linux/5.4.109+`