Package: mister-bump
Supported versions: Python 2.6, 2.7, 3.5, 3.6.Introductionmister_bumpis a Python-based tool for handling version numbering in Git projects.
It can be used from within Python via import, or via the command line.The idea is to automate the creation of version numbers within Git projects.  This can
be done by using the tool in a projects’ CI/CD build pipeline.In order for the tool to work correctly you should use the versioning approach suggested
below.InstallationInstallation can be done viapip.pipinstallmister_bumpBasic UsageOnce installed via pip, you can use the command line interfaceget-git-version, ormister-bump.If you have downloaded the project source, you can callmister_bump.pyusing the
same syntax.Note: You must call the script from inside the root directory of the Git project you want the version for.Basic call with no arguments:[08:18:39 user@localhost mister-bump]$ get-git-version
1.0.0rc1In the above call, thenextversion to be created will be1.0.0rc1.  So if
the Git project was pushed to master and the CI pipeline ran, the version used in CI
would be1.0.0rc1.The style can be changed to use.devfor development release (typically used as a post release version).[08:19:16 user@localhost mister-bump]$ get-git-version --style .dev
1.0.0.dev1It is possible to tell the script tonotincrement the detected version number.
This can be used for different versioning schemes.  For example, you may want to create
post release versions, rather than pre-release versions.[08:19:24 user@localhost mister-bump]$ get-git-version --style .dev --no-increment
0.3.0.dev1In this example thelastversion in Git is0.3.0, and the “deviation” (distance in commits)
is 1 - meaning that there has been one additional commit since that version.Verbose output can be obtained by passing the--verboseargument.[08:19:31 user@localhost mister-bump]$ get-git-version --style rc --verbose
08:19:40 [mister_bump:308][DEBUG] Fetching all candidate upstream versions
08:19:40 [mister_bump:31][DEBUG] Getting current git version
08:19:40 [mister_bump:38][DEBUG] Command: git describe --match=release-* --abbrev=4
08:19:40 [mister_bump:312][DEBUG] Candidate versions: release-0.3.0-final-1-gc68c
08:19:40 [mister_bump:322][DEBUG] Comparing candidate release-0.3.0-final-1-gc68c
08:19:40 [mister_bump:141][DEBUG] Version type = final
08:19:40 [mister_bump:141][DEBUG] Version major = 0
08:19:40 [mister_bump:141][DEBUG] Version minor = 3
08:19:40 [mister_bump:141][DEBUG] Version bugfix = 0
08:19:40 [mister_bump:141][DEBUG] Version deviation = 1
08:19:40 [mister_bump:141][DEBUG] Version hash =
08:19:40 [mister_bump:60][DEBUG] Current git branch is master
08:19:40 [mister_bump:86][DEBUG] Current branch is bugfix? False
08:19:40 [mister_bump:337][DEBUG] Version detected as "release-0.3.0-final-1-gc68c"
08:19:40 [mister_bump:267][DEBUG] Incrementing with MAJOR version increment.
08:19:40 [mister_bump:193][DEBUG] Formatted version is "1.0.0rc1"
1.0.0rc1Help can be obtained using the--helpargument.[08:14:40 user@localhost mister-bump]$ get-git-version --help
usage: get-git-version [-h] [-v] [-s {rc,.dev}] [-n] [override]

Get appropriate project version number based on Git status.

positional arguments:
  override              Override version number. Must be in the format
                        "release-0.0.0-000-aaaaaa".

optional arguments:
  -h, --help            show this help message and exit
  -v, --verbose         Enable verbose output.
  -s {rc,.dev}, --style {rc,.dev}
                        Style of suffix.
  -n, --no-increment    Do not increment version number.A Suggested Versioning ApproachThis is one way to do versioning, and it is the way that this tool was designed to work with.
If you have a different versioning approach this tool may not work as expected.Pipeline SetupMake sure themister_bumppackage is installed where your CI pipeline will run.  This could be a case
of installing on a server, adding the package to a Docker image, or simplypipinstalling it
within the CI pipeline.Normally you add versioning because you want to deploy something as part of your CI pipeline.
Set your pipeline up to perform deployment from themasterbranch (for release candidates),
andrelease-*branches (for releases).  You can optionally add deployment forbugfix-*branches
for bugfix release candidates.  Do not perform deployment onrelease-*-finalbranches
(more on that later), so add an exclusion for that too.If your pipeline is running in GitLab CI then you can add this to your.gitlab-ci.yml:only:-/^release-.*$/-master-/^bugfix-.*$/except:-/^release-.*-final$/In your CI script you can get the version number into an environment variable using:exportVERSION=$(get-git-version--stylerc)echo"VERSION is$VERSION"Use the$VERSIONenvironment variable when creating artifacts.Starting outWhen you first start version numbering on a project, there will be no tags, so the script
won’t detect a “current” version.  In this instance it will always return0.1.0rc1.You can either leave it like this, and accept that all release candidates will be created
with the same version number up until the first release, or you can create a newrelease-0.0.0tag on the project, which will mean each commit will
result in a new version number:0.1.0rc10.1.0rc20.1.0rc3If you set your CI pipeline to deploy on master updates then you will have new project
artifacts generated and deployed with each update to master.Note that the ``N`` in ``rc<N>`` indicates a distance (in commits)from the last release tag, so if
you merge multiple commits into master at the same time this will only result in one CI pipeline
running, and there will be gaps in the release candidate numbersCreate tagrelease-0.0.0Create dev branchXCommit 1 (distance of 1 commit)Commit 2 (distance of 2 commits)Commit 3 (distance of 3 commits)Merge branchXintomasterMaster CI pipeline will create version0.1.0rc3(norc1orrc2)Releasing a versionTL;DR- Create tagrelease-X.Y.Zpointing to masterEach master branch update will be a release candidate for thenextrelease, so0.1.0rc3is acandidatefor the0.1.0release.  When you decide you are ready
to cut a release simply create a new tag on the project.Assuming the last release candidate was0.1.0rc3, you would create a new tag calledrelease-0.1.0.In GitLab you can do this through the web UI by clicking Repository > Tags, then click
the greenNew tagbutton, type inrelease-0.1.0, and make suremasteris selected
as the source branch.Once the tag has been created, a new CI pipeline should run, and generate the artifacts for
your new release, with a version number of0.1.0.All subsequent commits to master will now be tagged as0.2.0rc<N>, as they are
contributing towards the next release.NOTE: The tag names are key to how ``mister_bump`` works, so make sure you use the
correct format (``release-<major>.<minor>.<bugfix>``)BugfixingTL;DR- To fixX.Y.Zrelease create branchbugfix-X.Y.Zpointing to master,make changes, create tagrelease-X.Y.Z+1. Cherry-pick fixes to master.This section explains how to fix a bug in a previous release.  In the examples we will assume
we have released0.2.0(i.e. there is arelease-0.2.0tag).In this instance we will be working to produce a0.2.1bugfix release.  You should think
of0.2.1as a bugfix for0.2.0.Create a branch calledbugfix-<release-you-want-to-fix>.  In our example this isbugfix-0.2.0.Develop your fix by committing to the bugfix branch.  As you go, each commit will result in
a0.2.1rc<N>version if your CI is setup to deploy on bugfix branch.Once your bugfix is ready to release create a tag forrelease-0.2.1, and base it on the
bugfix branch.  This will cause a new0.2.1version to be created in CI.Finally make sure all your fixes arealsoapplied to master (either manually or via
cherry-picking)You should now have something that looks like this:Tagrelease-0.2.0Branchbugfix-0.2.0Commit 1 (distance of 1 commit) - version =0.2.1rc1Commit 2 (distance of 2 commits) - version =0.2.1rc2Commit 3 (distance of 3 commits) - version =0.2.1rc3Tag bugfix branch asrelease-0.2.1- version =0.2.1Cherry-pick commit 1 onto masterCherry-pick commit 2 onto masterCherry-pick commit 3 onto masterBreaking change / Major releaseTL;DR- To close releaseX.Y.Zand move toX+1.0.0create tagrelease-X.Y.Z-finalpointing torelease-X.Y.Z.Major release numbers are typically reserved for breaking changes.  When you need to make a
breaking change, or just want to switch to a new major release (maybe due to a significant change)
you need to “finalise” the current major version, so you can move onto the next.Consider the following example:Lets assume we have the following released versions.0.1.0rc10.1.0rc20.1.0rc30.1.0(tagrelease-0.1.0)0.2.0rc10.2.0rc20.2.0rc30.2.0(tagrelease-0.2.0)If we carry on as normal, and start committing changes to master, the next versions would be0.3.0rc1,0.3.0rc2,0.3.0rc3, etc.Lets say we want to make a breaking change, and want to start work on1.0.0.  We need to
“close off” the0major release number, and move onto major version1.To do this we need to create afinaltag calledrelease-0.2.0-final, pointing atrelease-0.2.0.Thisfinaltag shouldn’t be used to cut a release, since it should be pointing to the same
thing as therelease-0.2.0tag.  It’s just used to tellmister_bumpthat we have finished with0.X.X, and we’re ready to start1.0.0.Continuing our earlier example, we would expect to see:0.1.0rc10.1.0rc20.1.0rc30.1.0(tagrelease-0.1.0)0.2.0rc10.2.0rc20.2.0rc30.2.0(tagrelease-0.2.0)Now we want to make a breaking changeTagrelease-0.2.0-final1.0.0.rc11.0.0.rc21.0.0.rc31.0.0(tagrelease-1.0.0)1.1.0rc11.1.0rc21.1.0rc31.1.0(tagrelease-1.1.0)Version numbers for Python packagesIf you are usingmister-bumpto version a Python package, you can call the package directly from yoursetup.py.#!/usr/bin/pythonfromsetuptoolsimportsetupimportmister_bumpsetup(name='<your-package-bame>',description='<Your package description.>',version=mister_bump.bump(style='rc'),...)Multiple version numbers in one projectIn rare instances you may want to manage version numbers for multiple deliverables
within one project, and you may want them to be versioned independently.  This is supported
inmister-bumpusing the--prefixoption.Lets imagine you have two packages within your project:fredandbarney.  You could configure
your CI pipeline to build and deploy those packages independently, based on the branch / tag names.
For example,fredcould be deployed from CI pipelines on tags starting withfred/(e.g.fred/release-1.2.3), andbarneycould be deployed from pipelines on branches starting withbarney/.When runningmister-bump, you can pass--prefix='fred/', andmister-bumpwill fetch the latest
version forfred/, increment the version number (according to the documentation above), and return
the new version number.Some things to note:If there is a/separating the prefix from the remainder of the tag, then you need to include
the trailing/.The version number returned bymister-bumpwill not include the prefix.  It will just beX.Y.ZrcN