Semantic versioning in large projects
A while back I wrote an article about software versioning for The Pragmatic Programmers. In that article, I suggested semantic versioning (SemVer) is a good approach to make the impact of your new releases immediately clear. My very wise friend Greg Thain had this to say about SemVer:
Not sure I believe in the utility of SemVer for larger projects. These tend to have a large and somewhat amorphous “interface”, and with a large enough user base, what is vital to one user is trivial to another. See also, Hyrums’s law.
Hyrum’s law, if you’re not familiar, says
With a sufficient number of users of an API,
Hyrum Wright, hyrumslaw.com
it does not matter what you promise in the contract:
all observable behaviors of your system
will be depended on by somebody.
I know Greg because of his work on the HTCondor project: a large project that does not use semantic versioning (although the version scheme is somewhat inspired by SemVer). Greg knows what he’s talking about. But in this case, I think he’s right for the wrong reason.
Why use semantic versioning
It’s true that people will find new and interesting ways to use software that the authors never intended or even considered. There’s an XKCD about that, of course. But using semantic versioning isn’t about what the users do in practice, it’s about what you intended. It’s an indication of when you expect things to still work and when you don’t. If something stops working and you intended it, then there’s nothing to fix. But if you intended something to keep working and it stops, then you have a bug to fix.
This doesn’t mean, of course, that you should break stuff william-nilliam and not care how it affects your users. At the same time, releasing software isn’t a commitment to support it forever in any imaginable use case. You have the right to decide what you’ll support and what you won’t. Your release versioning should reflect that.
In a project that uses a client/server model, there’s a good chance various pieces will be updated at different times, perhaps by different people. In these cases, semantic versioning — or something that approximates it — is important to helping users understand which pieces will work together.
Why not use semantic versioning
Of course, if your project places a strong emphasis on backwards compatibility, this is less of a concern. The Linux kernel is a good example. Linux could be at 2.ReallyBigNumber by now, but Linus Torvalds decided he’d occasionally increment the first number instead.
Some projects don’t have an API in the way we typically think of, or at least that’s not the primary way people interact with the software. Graphical applications are a good example of this. LibreOffice switched to calendar-based release numbering for the just-out 24.2 release.
Number how you see fit
Ultimately, you have to use the best version numbering scheme for the way your project works. In my opinion, you should default to SemVer unless there’s a good reason not to. But whatever you pick, document it clearly so your users understand what a new version number means.
This post’s featured image by Nick Hillier on Unsplash
