Package: vernum
VerNumConfigurable GitLab CI/CD-powered version numbering for project releasesLogo by Freepik/FlaticonPython module/CLI installationThe VerNum Python module is distributed as a PyPI module and can be installed like any other.Install with system-level Pythonpip3 install vernumInstall withpipxto avoid dependency collisionspipx install vernumInstall with a venv (depends on venv location).venv/bin/pip install vernum... or install as a Poetry dev dependencyCommandsThevernum maxcommandTakes 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"|vernummaxThevernum nextcommandTakes a single version number and, based on the configured numbering scheme and the selected increment, outputs the next version number.echo"3.4.5"|vernumnextpatchThevernum limitcommandTakes 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).SchemesVerNum supports multiple "schemes" for version numbering.SchemeDescriptionIncrementsExamplemajorJust a single version numbermajor4minorMajor, dot, minormajorminor4.2patchMajor, dot, minor, dot patchmajorminorpatch4.2.1minor-alpha-betaMajor, dot, minor, dot, and either a patch, alpha, or betamajor,minor,patch,alpha,beta4.3.alpha2Schemes support an optional "v" before the version number for inputs, including from Git, but output the result without a "v".The default scheme ispatch.Details of the minor-alpha-beta schemeTheminor-alpha-betascheme 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:majorchanges e.g. 5.6.2 to 6.0.alpha1minorchanges e.g. 5.6.2 to 5.7.alpha1betachanges e.g. 5.7.beta3 to 5.7.beta4alphachanges e.g. 5.7.alpha8 to 5.7.alpha9patchchanges e.g. 5.6.beta6 to 5.6.0patchchanges e.g. 5.6.2 to 5.6.3Use with Git tagsWe 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.gittag--list--mergedHEAD|vernummax|vernumnextpatch>.version
gittag-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 itBe 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 inputVerNum uses theWizLibframework for configuration and input control.Input to commands can come through stdinAlternatively, use thevernum --input <filename>to pull input from a fileThe scheme can be selected with an environment variable$VERNUM_SCHEMEAlternatively, the scheme can be set in a YAML configuration file; the application will try, in order:A config file location designated withvernum --config <filename>A config file location designated with a$VERNUM_CONFIGenvironment variable.vernum.ymlin the local directory.vernum.ymlin the user's home directoryWe recommend placing a.vernum.ymlfile 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:minorlimit:min:'4.2'Usage (GitLab CI/CD)VerNum is designed for use withing GitLab CI/CD using the configuration supplied by the Pro CI/CD framework to support the most common use cases.Best practices (in our opinion) dictate that version numbering happens downstream of source code, and the only record of a version number lives in the Git tags themselves. In other words, resist the temptation to add new commits just to bump a version.Use the providedvernumCI/CD configuration for the base case in GitLab, using either the defaultpatchschema or one defined in a local.vernum.ymlfile. Override the2-releasejob to perform the actual distribution or deployment operation.include:-project:'procicd/lib'file:'templates/vernum/base.yml'ref:'v1.0.0'2-release:script:-echo "Distribution or deployment process"The CI/CD component will add a set of jobs that:Output the latest version (based on Git tags in the branch being processed)Increment the version according to the configured scheme using an increment provided as a variablePlace the new version number in a job artifact called.versionfor use by later jobsAdd a GitLab release object and Git tag for the new version (usingrelease-cli)To trigger a release and indicate the increment, provide the variableVERNUM_INCREMENT. Treat this variable as momentary and keep it out of the settings. Provide the value in the "Run Pipeline" form or use theglabCLI:glabcirun--variablesVERNUM_INCREMENT:minorOr attach the variable to a push operation:gitpush-oci.variable="VERNUM_INCREMENT=alpha"The project also includes components that pre-specify the numbering scheme and include the exact right options for the "Run Pipeline" form. Please use thev1.0.0ref when including files from the Pro CI/CD library as they are subject to revision.templates/vernum/major-scheme.ymltemplates/vernum/minor-scheme.ymltemplates/vernum/patch-scheme.ymltemplates/vernum/minor-alpha-beta-scheme.ymlNote that the CI jobs contain a bug and will fail if no previous version matching the scheme exists (to be fixed).