Stop using version in package.json

[Cruikshanks]

Currently, we have each app report details about itself on a /health/info endpoint. For each app this returns the current commit hash and the version recorded in package.json.

All this then gets shown in our main /service-status endpoint (or /health/info in water-abstraction-system if you want to go direct!)

Normally, when we cut a release we're ok to just take whatever is on main and tag that as the next version. We run npm version [minor|patch] and both the tagging and the updating of the version in package.json is done for us.

But in a recent release main in a couple of the repos contained changes we weren't yet ready to include. No problem, we just have to check out an earlier commit and create the git tag there. This does mean though we can't run npm version and increment the version in package.json.

The issue came when our QA went to /service-status to double-check the versions now running. The commit hashes were all correct; we were running the version of the code we'd tagged for release. But the versions displayed were now out of sync with the git tags.

There are only 3 solutions as far as we can see

• wait until everything's been tested - just not practical
• go back to using git-flow and development/release branches - not on your life!
• stop using the version in package.json - 👈 😁

Whenever we 'cut' a release we create a tag at the commit we intend to push to production. The tag is our version, not what's in the package.json. So, if all our /health/info endpoints returned the result of git describe --always --tags instead they would be

• more accurate
• avoid this confusion

[Cruikshanks]

For those interested in git describe --always --tags

git describe returns a human-readable name based on the current commit reference, for example, v0.1.0-26-g92a2027.

The command finds the most recent tag that is reachable from a commit. If the tag points to the commit, then only the tag is shown. Otherwise, it suffixes the tag name with the number of additional commits on top of the tagged object and the abbreviated object name of the most recent commit. The result is a "human-readable" object name which can also be used to identify the commit to other git commands.

Git docs for git-describe

Our example v0.1.0-26-g92a2027 broken down means

• the last tag created for my main branch was v0.1.0
• there have been 26 commits to the main branch since that tag was created
• the abbreviated commit reference for the lastest commit is 92a2027

The g just denotes that the source control system is git.

For reference the git describe --always --tags command broken down means

• --always if no tags existed nothing would be shown. As a fallback we include this argument to tell it to always return the abbreviated commit reference for the last commit.
• --tags by default the command only works with annotated tags which is fine for us as that's all we use. But just in case we tell it to reference all tags created, both annotated and lightweight

[Cruikshanks]

All projects updated!