Releasing/Versioning of Software

Releasing is giving a software to the end user, once other phases like develooment, testing is done.

End user can be a QA if the development is done and software is released for testing on it.

End user can be a Customer, if all the phases of software development are done and software is ready for production.

While we release a software we give a version number to it. A version number looks like MAJOR.MINOR.PATCH, which will increment based on the type of changes we want to release in API/application.

Please refer to https://semver.org/ for Semantic Versioning.

1. MAJOR version when you make incompatible API/software changes.

2. MINOR version when you add functionality in a backward compatible manner.

3. PATCH version when you make backward compatible bug fixes.

   
   

Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.

Example:

snapshot of spring boot versions

In the image shown, versions 3.4.1 and 3.3.7 are stable spring boot versions and are recommended to work on, while 3.4.2 (SNAPSHOT) and 3.3.8 (SNAPSHOT) are pre-release versions, where (SNAPSHOT) is an extension, shows it's a pre-release.

When we talk about versioning, the first thing that comes to our mind is the version control system, most used in industry is Git and GitHub, a web-based platform that allows developers to: Store, share, and collaborate on code.

To create a release of an API or software using GitHub, we follow some steps as show below with a sample application:

1. Go to the repository of the software/API we want to release.

   

   Fig. Landing page after we open a repository

2. On the right hand side notice "Releases", click on it. You will land up to page as show below:

   

   Fig. Landing page after we click Release for the first time, it will look different during further releases

   
   

3. Click Create a new release.

   

   Fig. Create a new release

4. Fill up the Release informations:

   1. Choose a tag or create one: Here goes the version number. Like in the image shown below I used 1.0.0. This means it's a Major release as per the description provided by Semantic versioning Major.Minor.Patch in increments.

   2. Target branch: Choose the desired branch where you are willing to tag the release version. Generally the main/master/trunk branch contains the tag. so, choose it.

   3. Generate release notes: Automatically add the Markdown for all the merged pull requests from this diff and contributors of this release. If you want to use auto description to your release from git commits, choose this option. It will also include what changes are done by whom.

   4. Give Release title: Title for the release.

   5. Describe the release: Give description of the release. auto generated using point c. Generate release notes or give your own.

   6. Set as pre-release: Choose this option if it's not a production release and the application/API is still in the development stage.

   7. Publish release: Click it if you are ready to publish with all the changes you did otherwise click another option save draft.

   8. Save draft: Use it if not ready to publish but want to keep the changes related to releasing.

      

5. Once you click on Publish release, a tag will be created to your repository in the branch you choose.

   

   Fig. Release tag after creation

6. The initial page of repository will looks something like below, having one release in Releases section now:

   
   

   

7. Similarly let's say we got some bug fix/patches in master branch, the next version number will be 1.0.1.

8. If the changes are minor features updates not affecting the backward compatibility of API/application. It will be 1.1.1.

9. So we got three production ready releases in our repository with one major, one patch and one minor feature update. The releases section will show the updates as:

   

10. If we click on the Tags section, we can see all the tags for releases we had for application.

    

11. We can do edits or deletion to the created tags from the 3 dots on the right hand side in the page above. or can choose Releases from tab and can do edits, deletes or even comparison to releases we created tag for as shown in page below.

This tag allows us to get the code in exactly the state it was merged to the specified branch and released.

Once you set up the tags, your CI/CD pipeline setup will automatically detect the new tag and initiate the deployment process.

Tag creation can be achieved using git command as:

Syntex: git tag -a tag_name -m “tagging message”

Example: git tag -a v0.0.1 -m “first tag for this repository”

To see all tags created till now use:

git tag

To list only few interested tag, one can use regex as:

git tag -l “v.22.*”

You can see the tag data along with the commit that was tagged by using the git show command:

git show v1.0.0

Refer https://git-scm.com/book/en/v2/Git-Basics-Tagging for more on basics of git tagging.

You can also use this tags to create a new branch as:

1. Fetch all the current tags from the remote repository

git fetch --tags

2. Checkout the tag you want to make the branch from:

git checkout tags/<tag_name>

3. Create a branch off this tag. Bear in mind at this point the code is in a “detached HEAD” state meaning you aren’t working from the top of any branch.

git checkout -b new-branch-name

Depending on the development strategy used in your application you can choose to tag the branch at a specific point to have changes in that repository tagged to a specific point of time.

In the GitFlow way of development strategy, one can cut the branch from tagged master/main branch and do releases.

In trunk based development one can use tags to automate the build in CI/CD pipelines.

The versioning can also be based on commit number and date of the commit in trunk based development, which is quite popular in extreme programming nowadays.

Please refer my next blog on how to use these tags for continuous deployment.