How to manage sofware versioning

In this article we explore different ways of programmatically managing software using semantic version conventions. It’s not the purpose to discuss what is semantic versionning, but rather its implementation details.

High-level Overview

{
  "name": "app_name",
  "version": "1.0.0",
  "scripts": {
    "semver:major": "npm version major --no-git-tag && git tag $(jq -r .version package.json)",
    "semver:minor": "npm version minor --no-git-tag && git tag $(jq -r .version package.json)",
    "semver:patch": "npm version patch --no-git-tag && git tag $(npm version --silent | grep app_name | awk '{print $2}' | sed s/,$// | sed s/\\'//g)",
    "sem:patch": "npm version patch --tag-version-prefix=''",
    "tag:debug": "echo $(npm version --silent | grep app_name | awk '{print $2}' | sed s/,$// | sed s/\\'//g)",
    "tag:push": "git tag push origin $(npm version --silent | grep app_name | awk '{print $2}' | sed s/,$// | sed s/\\'//g)",
    "semver:prerelease": "npm version prerelease --preid=rc && git push origin HEAD --tags",
  },
}

• It goes without saying that app_name is an example, and it should be replaced by your project name.

Preparing the version number

By default npm version [patch|minor|major] prefixes the new tag with a v. While this is fine, in this example, we are removing it for the sake of clarity, convention and demonstration.

Using the --tag-version-prefix in the script

So we can either add the --tag-version-prefix flag to the npm script…

{
"sem:patch": "npm version patch --tag-version-prefix=''",
}

Using .npmrc

…or add this setting to a .npmrc file living in the root directory of your project

tag-version-prefix=""

{
"sem:patch": "npm version patch",
}

In both examples, the executing npm run sem:patch will:

1. update the package.json version

{
  "name": "app_name",
  "version": "1.0.1",
}

2. Create a tag with the updated version number (in this example, 1.0.1)
3. Add a commit with the version number to the branch history

On a side note, if you are running these commands on GitHub Actions, you should make sure to have the necessary permissions in place to commit to the repository.

Skip adding a commit with a version number

If you don’t care about adding a commit with the version, you can use the --no-git-tag flag, to update only the package.json AND then handle it separately with the git tag command. In the following examples, we use a technique called command substitution to grab the version number and pass it as argument to the git tag command.

The advantage of the first example over the second is that the first relies only on native command-line tools available in most UNIX systems (Linux, MacOS).

{
    "semver:patch": "npm version patch --no-git-tag && git tag $(npm version --silent | grep app_name | awk '{print $2}' | sed s/,$// | sed s/\\'//g)",
}

In this example, we use jq to parse the package.json file and grab the version number. It’s definitely easier to read, but it requires the jq package to be installed in your system. If the intent is to run these commands programmatically, for instance on GitHub Actions runners, remember to add steps to install the package.

{
    "semver:patch": "npm version minor --no-git-tag && git tag $(jq -r .version package.json)",
}

Pushing the tag to the repository

It’s a good idea to separate the tag creation (with or without committing) from the act of pushing the tag to the repository. At times, you may want to test the tag creation without having it pushed to the repository.

{
  "tag:debug": "echo $(npm version --silent | grep app_name | awk '{print $2}' | sed s/,$// | sed s/\\'//g)",
  "tag:push": "git tag push origin $(npm version --silent | grep app_name | awk '{print $2}' | sed s/,$// | sed s/\\'//g)",
}

The `tag:debug` script will print out the version number, while the `tag:push` will effectively push it to the repository (as a tag).