Simple Semantic Versioning on GitHub

I needed automated semantic versioning in GitHub. The existing options didn's strike the right balance for me, so I built Simple Semantic Versioning and launched it to the GitHub Actions Marketplace. Read on for the why and the what.

What's the need?

Simple Data System, Sodium Skies' product, is single-tenant hosted as an important part of our security architecture. There's no risk of leaking one client's database data to another, and should a client's system be hacked the blast radius is limited strictly to them.

So I wanted to attach a version number to each installation. Records are one thing, but when it comes to support and to conversations about upgrades, being able to see the version right there in the running software is invaluable. Ideally a semantic version: bump the micro (patch) number on every code change (for some value of every), the minor version for every new feature and the major version on breaking changes. That way we can see how far a running instance is from the latest version.

Buy beats build – what's already out there?

I'm not going to do this manually, incrementing a version on each commit. It has to be automated. GitHub will have me covered, right? Right?

Wrong. Nothing in GitHub – not even an increasing commit number.

OK let's try that again. Someone must already have published an action for this? There are several excellent actions out there that seem to fall into two categories.

Git Semantic Version by Paul Hatcherian and semver-action from the IETF, both depend on conventional commits:

• Commits annotated with `feat` update the minor version number (you can customise the rules in Git Semantic Version)
• `BREAKING CHANGE` updates the major version
• everything else updates the micro version

semver-action by Carlos Henrique Guardão Gandarez does something similar, with disciplined naming of branches instead of commits.

At the other end of the spectrum, gh-action-increment-value by Yoichiro Tanaka drops the complexity but increments a monolithic number not a semantic version. (It had some useful ideas and really accelerated my own development – thank you Yoichiro! 🙏)

None of these struck the balance I was looking for: semantic versioning without impacting my development practices. I was going to have to build this myself!

Enter semver-bump-micro

Looking at what was already out there really helped me understand my needs. If I don't want to annotate my commits or my branch names (what if I forget an annotation? 😬), how am I going to differentiate between micro, minor and major version bumps?

Well all I really need to automate is the micro increments – the ones that change too frequently to do manually. Minor bumps on feature completion and major bumps on breaking changes should be much less frequent and should be intentional. I can bump the version for those manually.

So I built `semver-bump-micro` to keep a simple semantic version up to date with every push to main. Just increment the micro portion. And no complications (eg no annotations like 1.0.0-beta.2).

I chose to increment on each push, not each commit. It tracks changes to deployable code with a useful increment rate. It avoids inconsistencies between developers’ commit habits (I micro-commit, others don't). And it's much simpler to implement than digging into the merge to count commits.

Building the action was shockingly simple. Getting the workflow right was harder. I wanted to make the version bump part of the triggering commit (`git commit --amend --no-edit`). The first time I ran this it flattened my entire commit history in GitHub, due to interaction with how I'd checked out the code. Fortunately I was able to restore the history from my development machine and resolve the problem!

I also realised, long before I'd finalised the workflow, that the same action could be used to manage minor and major increments...

Minor and major updates in v1.1.0

Remember I said all I was interested in automating was the micro increment? I could edit the minor and major versions in separate commits, or even directly in GitHub. But with very little extra code and two new workflows, I can manage the entire semantic version simply and consistently through the action.

So version 1.1.0 was born. (Yes I use my own action and workflows to track its own development – eat your own dogfood!) Now semver-bump-micro automatically bumps the micro version and manually bumps minor and major versions. The repository name is...no longer accurate.

Now and next

semver-bump-micro is in a public repo under an MIT license, and is available in the GitHub marketplace as Simple Semantic Versioning. Now there's a name that encompasses what it does!

I hope it's valuable to others. What's next depends on what people need, or on what I need next. Some possibilities:

• Manually editing the version file through the action, eg to correct errors or make specific intentional changes
• Tolerance to suffixes such as 1.0.0-beta.2
• The ability to add and remove suffixes
• Managing a semantic version in a larger file, eg a .json config file

Try it on the GitHub Marketplace and let me know what features you’d like next. Or let me know how you've tackled versioning in your own projects.

Thanks for reading

Image credit: remixed from black and red digital clock by Vincent Chan

#SemanticVersioning #Automation #GitHubActions #DevOps #OpenSource