Semantic versioning (or semver) is a very basic concept that stirs a bit of controversy on the internet. A quick google for “semantic versioning problems” brings back a number of essays about all the shortcomings.
They do make fair points, though to be able to appreciate the deficiencies, it’s good to just understand the thing first. So for people who have never been exposed to semantic versioning, I thought I’d make a short micromaterial on it.
Full disclosure: this is very much an homage to the wonderful https://questions.wizardzines.com/ by Julia Evans, and is based on her https://github.com/questions-template/questions-template.github.io.
The live site is here:
https://semver-questions.netlify.app
Skills to practice – what do the numbers mean?
One thing that working programmers need to deal with is upgrading their dependencies. When making the decision to upgrade (and when/how/etc), it’s good to know whether a particular update will break everything. Ideally it wouldn’t and also ideally we’d have time to test out everything (or even better, have an automated system do it for us!).
As a shorthand, we can use semantic versioning to at least give us a clue about what the maintainers of the dependency think they’ve done. If they are just patching bugs, and nothing else changes, that’s a patch version. If they added some features, but everything old still works, that a minor version.
If, on the other hand, they broke ANYTHING that somebody somewhere might have been using in the public API, that should be a major version increment.
Once this understanding is automatic, it gets much easier to accept all those dependabot PRs for your GitHub repos.
Skills to practice – which numbers to pick?
For those who are maintainers themselves, they need to know which numbers are appropriate to choose to adequately communicate to their users (and the systems of those users) which things changed in a new release.
The considerations are essentially the same as the above, but this time you need to use the numbers to convey meaning instead of just interpreting them.
Question and Answer
I really like the low-stakes approach to guessing and revealing the answers. The “I learned something” star button is a very nice touch as well (both aspects of the original template).
I thought about doing something in a similar vein as my https://cron-trigger.netlify.app/ micromaterial, where the questions are autogenerated, since the answers are fairly predictable (after all, that’s the entire point of semver!).
But this concept is simple enough that even just going through this basic (hardcoded) Q&A is probably enough to understand and be able to apply the concept.
Thanks again to the wonderful Julia Evans, and if you haven’t checked out her https://wizardzines.com/ yet, do yourself a favor and head over there. It’s a very “micromaterials” approach, and a bargain at 10 times the price.
micro materials blog 