They changed it again?

Feb 2025

SemVer normalizes constant change, placing a toll on individuals and small teams. This essay offers a more sustainable alternative.

A bias towards change

Small software is built by small teams on small budgets. It gets used for years, even as it ages and starts feeling out of place. Nobody wants to change it because it gets the job done. Nobody has the time, budget or inclination for the big rewrite.

This tends to make software engineers uncomfortable. Something feels wrong to us when software isn’t changing. We’re perfectionists. We see warts and they rub us the wrong way. Because of this, we’ve learned to live on a hamster wheel of updates, changing APIs, new tools, better tools, and neverending new ways of doing the same old stuff.

Think of software as it was, say, ten years ago. Other than using LLMs and other AI tools, what can you do now that you couldn’t do then? Is email that different? How about Slack? How about an online store? They’ve all changed a lot, but what exactly has all this change allowed you to do?1

What software looks like when it doesn’t break

As a counterpoint, think of programming languages. Even ten years after their first stable release, languages like Go or Elixir have yet to come out with a 2.0 version. They’ve changed a lot, but always made sure existing programs continue to compile and run2.

The browser trio of HTML, CSS and Javascript are another great example of backwards compatibility3. Even today, you can still view the internet’s first web page that’s almost 35 years old.

Could you imagine this kind of backwards compatibility extend beyond programming languages to the libraries, data formats, tools and operating systems we use? Does the concept of software being finished strike you as strange? How did we get to a place where the mere idea seems inconceivable?

SemVer, the enabler

Now let me get up from my armchair, stop philosphizing and talk instead about something more concrete: SemVer.

As a widespread practice, Semver reinforces a set of assumptions. As engineers, we’ve internalized these assumptions to the point of forgetting they exist. For example:

  1. Software is never finished. It always changes and incorporates new functionality. In fact, software that hasn’t changed in a while is suspect.
  2. Like a ship of Theseus, we can replace parts of software over time to adopt new ideas percolating in the industry. Some would say we should change it.
  3. Stable software offers no guarantees regarding future incompatible changes beyond announcing clearly when they take place.
  4. When a backwards-incompatible change is released, it is normal for users to choose between adapting to this change or foregoing any future improvements.

These assumptions may be acceptable for large, well-funded teams writing “industrial-grade” software. But they’re detrimental to smaller teams and can be outright hostile to individuals. I’d also suggest they’re a big contributor to OSS maintainer burnout. You could say that some of us get caught on the wrong side of the hamster wheel.

Versioning for stability

StaVer, short for stability versioning, is an alternative to SemVer. It starts by drawing one clear boundary. Software can only ever be in one of two states:

To that end, a StaVer version is made up of two numbers, for example 0.37. The first number is a stability indicator: 0 when the software is unstable and 1 when it becomes stable. The second number is the actual version number.

For unstable software, the system includes a couple of other restrictions. The version number can be any number between 1 and 99. This is done to discourage what is jokingly referred to as ZeroVer.

Being on 0.x means the software is unstable, so stable software shouldn’t be allowed to depend on it. This rule should be enforced by a package manager.

For stable software, the rules are not as strict. The version number can be any positive integer, including 0. The convention is to start from 1.0 and increment. But you can also use a calendar based scheme like 1.YYMMDD.

Stable software can also ship prereleases. They’re a useful tool for rolling out updates in a safe and backwards-compatible manner. Prereleases are not available for unstable software, since it carries no guarantees to begin with.

Prerelease versions look like 1.0-alpha1, 1.0-beta8 and 1.0-rc123. They consist of a label (think [a-z]+) followed by an integer greater than 0 (think [1-9]\d*). When ordering prereleases, labels are sorted alphabetically and within each label numbers are sorted numerically. You can create as many prereleases as you want.

Unstable software: encouraging experiments

StaVer is not meant to discourage you from experimenting. In fact, I feel like it could achieve the opposite. It doubles down on SemVer’s written but frequently ignored rule that 0.x.y software can have breaking changes between any two versions. With StaVer, 0.x is your license to experiment. It lets others know they need a labcoat and safety goggles before they join you.

With StaVer, you don’t have to release a new 0.x version the moment someone finds a bug in your code. Remember, you didn’t promise them stability to start with. If on average you release a new version every two weeks, you can stay on 0.x for over 4 years. That’s plenty of room to experiment. If you release once a month, you can stay on 0.x for 8 years, which is enough time to create a new programming language.

What StaVer tries to teach you is to use 1.0 as a signal that you’re done tinkering. Others can now depend on your work. They can spend their days focusing on their own problems–without you getting in their way.

Stable software: just enough progress

When you hit 1.0 your software shouldn’t have to suddenly freeze in time. You should still be able to grow it, slowly and deliberately provided you don’t break anyone’s code. To that end, your programming language and package manager need to offer two capabilities.

First, as your software is marked stable and gets more use, you might learn an API you provided was, in retrospect, a mistake. A frequent reason is the API makes it easy for users to do the wrong thing. Since you promised not the break API compatibility, what can you do to help them?

The solution, to my mind, is to give package authors the ability to mark APIs as obsolete. You introduce an improved but optional API and mark the old one as obsolete. Marking a function, module or class as obsolete should emit some warnings during compilation. But an obsolete API should never go away. Your users should be able to silence those warnings and go about their business in perpetuity.

Second, your users should know when an API they use is no longer secure. This happens often enough for cryptography-related APIs. We shouldn’t lock people into bad security practices for the sake of backwards compatibility. Package authors should be able to mark APIs as insecure. Attempting to use an insecure API should fail during compilation. But users should still be able to turn those hard failures into warnings if they want. Even insecure APIs should never go away.

Packages built around SemVer encourage a “my way or the highway” attitude towards users. It doesn’t have to be like that. If your users feel like they know what they’re doing, if their software is a toy or an experiment, don’t lock them out of future updates. Offer them the choice. Trust them and let them deal with the consequences on their terms.

Who StaVer is for

I believe a versioning scheme like StaVer with clear labels for stable and unstable software can benefit two very different constituencies:

  1. Folks who are engaged in end-user programming, homecooked software, barefoot development, situated software, etc. For them software scratches an itch or answers a sudden question. Ideally, they’d like to write the damn thing once and stop fiddling with it. What I don’t think anyone wants is to write software once and throw it away. They might need to make a small tweak in a year’s time. A tweak should never have to start with spending hours on inconsequential updates.
  2. Small teams on small budgets, writing software for professional or business use. They want to make choices with a certain degree of confidence, knowing they didn’t just commit themselves to a lengthy future rewrite. When they look at a piece of software, they want to know just how much they can depend on it. They want a better indicator of trustworthiness than when the software was last updated.

SemVer is not really serving either of these groups well. To my mind, there’s huge potential in changing that.

In the next few months I’ll be attempting to write a draft spec for StaVer. If anything, it’ll give me an opportunity to try my hand at writing my first specification. If you’re interested, or you have any questions or thoughts to share, get in touch using the links in the footer.

Addendum 1: Useful package manager / compiler features

Here’s a list of StaVer-related features for package managers and programming languages to implement. I’m sorting them loosely in the order of imprtance. Some of these I mentioned in the essay, others I left out to prevent myself from turning this into a whole book.

  1. Enforce that stable software doesn’t depend on unstable software.
  2. The ability to withdraw a version. Table stakes, but if a new 1.x version breaks backwards compatibility, your only recourse should be to withdraw that version.
  3. Mark APIs as obsolete. Allow them to continue working with silenceable warnings.
  4. Mark APIs as insecure. They shouldn’t compile by default but users should be allowed to turn the error into a warning.
  5. Enforce that APIs remain unchanged at the function or type level (like Elm does).
  6. Have built in tooling for compatibility tests, tooling that can test against an array of different versions.

Addendum 2: The case against patch versions.

SemVer versions are made up of three numbers, like 1.2.3. These are referred to as MAJOR.MINOR.PATCH. StaVer could simply use the same scheme and state that MAJOR can only be 0 or 1. But only having two parts in the versioning scheme, has a few other benefits:

  1. Since the first number can only be 0 or 1 , it becomes easier to express and reason about version requirements (see below).
  2. Seeing 1.2.3 doesn’t tell you if the current release was preceded by 5 stable releases or 25. A single number can be a better indicator of maturity.
  3. Even though SemVer explicitly states that any change is permitted at any time for 0.x.y software, lots of developers treat patch versions as backwards compatible. StaVer aims to avoid that and encourage folks to experiment.
  4. Having two version parts instead of three helps easily distinguish between StaVer and SemVer.

Addendum 3: Version requirements

Let’s go over version requirements for a moment. One of the benefits of only having two parts in a version number is you can express requirements without many of SemVer’s gymnastics. Here’s an outline of how you’d require versions:

These should cover most needs provided the package manager can guarantee two rules are followed. First, stable software can’t depend on unstable software because you would inevitably end up with breakage. Second, you can’t depend on both stable and unstable versions of the same package at once.

Footnotes

  1. The one major exception I can think of is Figma with its emphasis on real-time collaboration inside documents. I don’t think anything like it existed ten years ago. ↩

  2. Programming languages can’t afford to break people’s code. When they do, they meet a lot of resistance. The Python community needed over a decade between the release of Python 3.0 and the last Python 2 release. It may have felt like an eternity, but they were right to take so long. Killing Python 2 earlier could have splintered the ecosystem or lost them a language’s core asset: its users’ trust. ↩

  3. At the same time, these languages and their labyrinth of tools also teach us a hard lesson: sometimes you should take a little time before committing to backwards compatibility. ↩

  4. Open ranges only go upwards because any downward range can be expressed as a closed range. For example, “any version below 1.11” is 1.[0..10] ↩