Semantic versioning in large projects

Photo of numbers as on train station or airport departure/arrival boards.

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,
it does not matter what you promise in the contract:
all observable behaviors of your system
will be depended on by somebody.

Hyrum Wright,

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

Ben formerly led open source messaging at Docker and was the Fedora Program Manager. He is the author of Program Management for Open Source Projects. Ben is an Open Organization Ambassador and frequent conference speaker. His personal website is Funnel Fiasco.


Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.