Automatic Version Increments With Reliza Hub: 2 Strategies

This article describes how to set up automated version increments for use in CI build pipelines. I will go over 2 possible strategies: for simple CalVer workflow I would be using open-source Reliza Versioning tool. For fully synchronized workflow I would be using Reliza Hub SaaS.

Update: Please check our tutorial for more advanced use cases of Reliza Hub.

I Choosing Versioning Schema

For a project architect, one of the necessary first steps is to choose a Versioning Schema. Two most popular conventional models for today are SemVer and CalVer

Both have their pros and cons. Discussing them in details is out of scope of this article, however I will highlight the differences very briefly.

Main benefits of SemVer are that it has a strict convention and allows to estimate amount of changes between versions by just looking at actual versions.

For CalVer, main benefit  is that it allows to quickly see version relevance from today’s prospective (by establishing the difference between version’s date and today’s date). This part is essentially missing from SemVer, since SemVer versions tell nothing about when they were created.

However, downside of CalVer is predictably lack of difference semantics – for example, a year difference in CalVer versions may only be in a single line of code – and CalVer version usually would not have enough semantics to compensate. Even though CalVer is less conventionalized and actually presents by itself a class of version schemas which common pattern (usually, year and month).

So with these and other considerations (i.e., certain tools would require to use particular schema), it is required to pick a schema for the project.

II Simple workflow with Reliza Versioning OSS

Simple standalone workflow is usually based on automatic increment of previous version referenced somewhere in the source code or in the build process.

Reliza Versioning Open Source Solution has CLI that may be used in-place for version auto-increments in such workflows.

Let’s say we are using Ubuntu flavor CalVer (YY.0M.Micro). If we need to generate first version, we would run

 docker run --rm relizaio/versioning -s YY.OM.Micro 

Which would produce CalVer version based on today’s date. Since I’m writing this in February 2020, I’m currently getting 20.02.0.

Let’s now assume that I have an old version referenced that happens to be 20.01.3 and I need to do CalVer style bump on it. This means, that if date has changed, it will bump date first, so if I perform:

docker run --rm relizaio/versioning -s YY.OM.Micro -v 20.01.3 -a bump

I would get 20.02.0 (again, I’m writing this in February 2020).

Note that, if we’re still in February 2020 and our previous version is 20.02.4, running simple bump on that would produce 20.02.5, since only micro component may be bumped.

Now, if I deliberately only want to bump micro component and not bump date, I can run 

 docker run --rm relizaio/versioning -s YY.OM.Micro -v 20.01.3 -a bumppatch 

This would in turn produce 20.01.4.

Simple enough? All that is left is to introduce this run command inside build pipeline.

Now, similar strategy works with SemVer:

docker run --rm relizaio/versioning -s semver 

would initialize version at 0.1.0.

docker run --rm relizaio/versioning -s semver -v 3.8.2 -a bump

Would produce 3.8.3.

If we would to bump minor instead (and get 3.9.0), run

 docker run --rm relizaio/versioning -s semver -v 3.8.2 -a bumpminor 

Or to bump major (and obtain 4.0.0):

docker run --rm relizaio/versioning -s semver -v 3.8.2 -a bumpmajor 

III Synchronized Automated Workflow using Reliza Hub

Reliza Hub is a deployment and release metadata management tool. Above other features, it keeps track of project version schemas and version pins in project branches.

What is version pin in a branch? Suppose we have SemVer schema and we have Release branch built in December 2019, and we also have our regular master branch. To distinguish between those branches, it is a good practice to keep branches on different minor versions (or in certain cases on different major versions).

This means that Master branch may have 1.3.x pin, while release branch may have 1.2.x pin. This way we can understand which branch a release belongs to just by looking at major and minor components of the version.

Similar effect may be achieved with CalVer versioning – suppose we’re using Ubuntu style CalVer as above (YY.0M.Micro). Then we may choose to pin some stable production branch to say 2019.11.Micro, while keeping our master branch on the latest (YY.0M.Micro) schema. Effectively, Reliza will bump version according to current date and resolve conflicts via increments of Micro component. It is very similar to SemVer, main difference is that Pin is usually set on the date and not on major / minor combination. More details about different version components can be found in the README of Reliza Versioning repository on GitHub.

Let us now discuss how to mount fully automated workflow on Reliza Hub (note: Reliza Hub is currently in the public preview – until mid-June 2020, and after that there will be a free tier for individual developers – see more pricing details here).

First, navigate to https://relizahub.com , read terms and if agreed either authenticate with GitHub or click OK. Then create your organization and navigate to Projects:

Projects in Reliza Hub
Projects in Reliza Hub

Then click on plus-circle icon to create new Project:

Add New Project - Select Project Version Menu in Reliza Hub
Add New Project – Select Project Version Menu in Reliza Hub

Enter desired project name and select one of provided version schema templates or click Custom and then enter your own custom project version schema (again refer to Reliza Versioning GitHub Readme for details on available comopnents).

You may also enter details of your VCS repository for this project or skip this step at this time – after all it is not required for the version synchronization workflow we are discussing.

Click “Submit”. Your project is now created.

Notice that the system has automatically created “master” branch for you. If you click on it, you will see releases of this branch registered in the system (predictably, there are none at this point). Also notice, that master branch’s version pin matches project’s version schema exactly.

If you want, you may modify the version pin after clicking on the wrench icon above releases and thus expanding branch settings.

Branch View in Reliza Hub
Branch View in Reliza Hub

Now if you click on the plus-circle icon in the Branch column, you would be able to create release manually and system would auto-assign first version for you – 0.0.0 in ourcase. Every next click on the plus-circle (Add Release) would call version synchronization logic and yield next version (making sure that every version is returned only once).

However, what we really want here is to configure programmatic approach. Here is how:

First of all, we need to generate our API Key. For this, first expand the project settings menu by clicking on the wrench icon in the Project column:

Reliza Hub - Wrench Icon To Open Project Settings
Reliza Hub – Wrench Icon To Open Project Settings

Then in the project settings menu click Generate Api Key and it is best to store obtained id and key in your favorite vault solution. Note that subsequent clicking on “Generate Api Key” would re-generate the key and make the old one invalid.

Once you have the key, you may use Reliza Client docker container to obtain Version Assignment from the system. The call needs to be made as following:

docker run --rm relizaio/reliza-go-client getversion -i $your_api_key_id -k $your_api_key -b master 

Notice here that getversion keyword is a trigger to obtain version details from Reliza Hub. -i parameter stands for your api key id and -k parameter for api key itself, also -b parameter is required and denotes branch.

The tool would return next version for the branch in the json format, such as {“version”:”1.1.5″}.

It is also possible to supply optional –pin flag for Reliza Go Client, which is required for new branches or would update version pin for existing branches. In example, if we want to create new Feb2020 branch, with SemVer version pin 1.2.patch, we would issue command as:

docker run –rm relizaio/reliza-go-client getversion -i $your_api_key_id -k $your_api_key -b Feb2020 –pin 1.2.patch

More details about Reliza Go Client are provided on its GitHub page.

Summary

We covered above:

1. Simple workflow to auto-increment versions in the build pipeline using open source reliza versioning tool.

2. More advanced automated synchronization workflow using Reliza Hub Metadata Management solution for synchronization. Note that Version Synchronization is a small portion of Reliza Hub features, but discussing other functionality would be out of scope of this article.

One reply on “Automatic Version Increments With Reliza Hub: 2 Strategies”

Comments are closed.