Hacker News Reader

Comment by ajmurmann | Hacker News Reader

I find this framing to be too inward looking. SemVer isn't for me as the library developer, it's for users of my library. What it really means in that context for most users/customers outside of toy projects is:

EXPENSIVE-HIGH-RISK-UPGRADE. MEDIUM-RISK.LOW-RISK

There is a carrot-side to this but that usually only matters in specific cases for a subset of users.

EDIT: one small practical addition: If you are fixing a big that requires very large changes to how things work at a more fundamental level, I'd at least think twice about shipping that in a patch. While it technically fits the definition of SemVer, it might violate implicit expectations of users who are using your library in production. The change really needs to carry its weight.

View on HN

At this point, I feel like the version numbering of semi-ver has lost all meaning.

I've been broken by every level of version bump. I've seen APIs that went from 1.0 -> 2.0 and really were only backwards incompatible because of a single method change.

I've seen countless major changes to method signatures from a 1.0 -> 1.1 bump.

I've even seen breaking API changes from a 1.0.0 -> 1.0.1 bump.

It seems like everyone has a different feeling on when those numbers should be rolled. That inconsistency makes it impossible really understand what an upgrade is going to do without tests.

Not every project follows semver. Just because there are numbers with periods interspersed doesn't mean it's semantic versioning. People have been throwing numbers together to communicate something about what it is for a long time now, long before semantic versioning was formalized.

Which is exactly the point I'm making.

Semver only really works if everyone, or most everyone, is following it.

There are a lot of build tools that make that assumption. (cargo, npm, gradle, pip, for example).

Without that, you end up needing to have very deep understandings of your dependencies and their subdependencies. Otherwise, it's impossible to know what will happen when you update something.

I get more what you're trying to say now. To some degree, some people are definitely failing to adhere to semver when they're part of a larger ecosystem that needs it, like the ones you mentioned. Regardless of what versioning a module uses internally for development, they should be exposing a good semver compatible version to the tooling that uses them that expects it, but they often fail in this.

There is, alternatively, likely some assumption at this point in end users that some random project on github or elsewhere might be following semver even if they haven't stated as much, and without a stated intention to follow semver by the project and showing that they are willing to do so that means little and is a poor assumption. That's not necessarily applicable to your original point though.

It doesn't need everyone to follow it; it just needs library maintainers to declare when they do follow it, actually mean it when they do, and check their own dependencies for breaking changes.

ie a library that declares it uses semver should create an abstraction barrier around all of its dependencies, such that the user should only need to care about declared breakages in their direct dependencies.

This is funny because everybody makes mistakes , so of course people fail at semver.

However, if you are the maintainer of a popular cargo package, and make a mistake, people _will let you know_. Because a lot of people in the Rust ecosystem expect versions to follow semver.

Crates that fail to adhere stop being used, get bad rep, people fork them, and keep them stable, making them loose users.

Rust actually has a tool called rust-semverver that does an AST to AST diff of the current version of a crate that you want to release, with the latest release, and suggests how to increment the version.

It can list all API changes, and it will tell you which changes are minor, major, or patch.

You can use it in your deployment workflow on CI to, e.g., deploy a new version of a crate only if, the changes follow the version change that was specified. Such that, e.g., if you bump your 2.0.0 crate to 2.1.0 but your crate has an API breaking change, the tool and CI fails telling you that you need to change the version to 3.0.0 because of these changes.

Well, it seems like most of the critical packages in the Rust ecosystem are at 0.x so I’m not sure how much this is being done in practice.

I think some of this is because even package maintainers have a hard time deciphering what is potentially "breaking". There was a great talk at GopherCon about an ambitious project whose goal was to be able to detect if you made backwards incompatible changes, which on the facade seems easy (to some folks, apparently) but is in fact not.

That’s funny, because on the face of it, detecting breaking changes seems impossible to me, not easy.

I remember the speaker going pretty in depth on "what looks obvious" vs "bet you didn't know this changes behavior".

That said, my sentiment is the same as yours. I was surprised that even needed addressing.

Because in reality every change is breaking to someone. Some just break more stuff than others.

No software story is more classic than the bugfix breakage. There is a reason versions are pinned. There is a reason lockfiles exist.

---

Whatever your intentions, versioning is HIGH.MEDIUM.LOW breakage.

I don't degenerate versioning at all; I find it to be very helpful. But don't pretend it guarantees something that it can't.

Versioning is simply a best-effort communication of risk.

MARKETING.PM.ENG is closer to my experience

Somebody should come up with a name for this and craft a manifesto on a website :-)

Realver.org? Enterprisever? Corpver?

Hah! I had something similar awhile ago: https://twitter.com/lorenc_dan/status/1209289792569131008

I particularly love your followup: https://twitter.com/lorenc_dan/status/1209290259386769408

Please add this to the Twitter thread. I'm dying laughing at how true this is

The PLaneT network package manager did it even simpler: APIBREAKING.NONAPIBREAKING. Which might be interpreted as NEEDSENGINEERINGLOOKBEFOREUPGRADE.SAFEAUTOUPGRADE.

This was used for PLT Scheme, and was a rather nice 90%+ very lightweight solution.

If you were doing a package where backward-compatibility was a very high priority, you might be at PLaneT version 1.x forever.

If you were doing rapidly evolving research, and wanting to share code, while not surprise-breaking people who might use your stuff, you could end up with a large major version. For example, a package by Dave Herman (of Mozilla and Rust fame) got up to 9.x in only 2 years. http://planet.racket-lang.org/display.ss?package=javascript....

I don't recall whether anyone ever encountered unexpected breaking changes in practice that the version number didn't indicate. I'd guess probably. It wasn't a 100% solution alone.

PLaneT also supported specifying in a code file import which versions of the package you were known to work with (like meaning "major version 4, with minor version 2 or later; or major version 5"), with automatic installation of those.

You could also mix multiple versions of a package in a system, in the normal case (though maybe not if you had something like singleton state or resource that multiple versions of the package wanted to control). This seemed very valuable for pulling in lots of small open source dependencies, directly and indirectly, from different developers.

One downside of this simple approach is that it's bad as a "marketing version number". Like if you wanted to convey the value of large new features (or maybe talk about them in an easy way, like "version 4 foo features"), but you've been sticking to version 1.x backward compatibility the whole time. So there was a separate marketing version number, which seemed confusing enough that there must be a better way. But it was at least 90% there.

I think the difference between minors that include non-stop breaking features and patches actually is important. If you run a mission-critical system you want to minimize risk as much as possible but also get your needed fixes, especially if they are for CVEs. If it was a fair assumption that we only ever break things on purpose the PLaneT versions would be totally sufficient though.

Good point. If we had something PLaneT-like, I wonder this-is-important-security-fix should be included in the version number (maybe a big `S` suffix), or separate. Or whether it much matters.

Security fixes are exceptional situations, requiring scrutiny from developers and also sometimes by end users. To understand the implications, what's affected, the urgency, any other impact, etc.

And we also have situations like a popular distro often shipping regressions in their security updates (including a "bricking" one for some hardware platforms last year, which threatened some appliances I had installed overseas).

Given this need for scrutiny by at least developers, I don't know whether having is-a-security-update information in the version number itself helps, or is just as well (or better) represented separately.

One distinction that might be intuitive and relevant... We already know that is-backward-compatible-with-previous-version(s) is something that could be handled more flexibly separate from the version number, such as for updating changing knowledge about that after a version release -- but there's lightweight benefits to being able to talk about that in a version number, such as in the import line. But the import line doesn't need to talk about security update handling, and probably shouldn't.

I see the middle number as "RISK-FREE-UPGRADE" - if I bump that number in one of my packages it means there's a new feature, which should have no impact at all on existing code.

That's because you are a library author, and because you are following the standard.

A library user can't afford to assume any change is risk-free. Even when the author claims it is.

I like the thought process here.

In theory MINOR and PATCH are both supposed to be low risk. The risk only increases if the developer/process in control of the versioning doesn't recognize when a fix or feature contains a breaking change.

This is how I handle my libraries too. My standard is that you will never have a breaking change in any of my minor or patch versions.

I may ship new API in minor versions, and if I need to do an API rewrite, there will be a few years where you can use both APIs, then in a future major version, I will deprecate the old API (emit warnings), then in yet another future major version, I will finally remove the old API.

Basically my expectation is that if you use my library, you’re set. You’ll get new features with minimal stress.

More like NEED-REFACTOR.CHECK-TODOS.CHECK-FIXMES

Reply on news.ycombinator.com