6 ms·

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 f

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.

andrew_ 5y ago
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.
mrits 5y ago
MARKETING.PM.ENG is closer to my experience
- ithkuil 5y ago
  Somebody should come up with a name for this and craft a manifesto on a website :-) Realver.org? Enterprisever? Corpver?
  - dlor 5y ago
    Hah! I had something similar awhile ago: https://twitter.com/lorenc_dan/status/1209289792569131008 https://twitter.com/lorenc_dan/status/1209289792569131008
    - BeefySwain 5y ago
      I particularly love your followup: https://twitter.com/lorenc_dan/status/1209290259386769408 https://twitter.com/lorenc_dan/status/1209290259386769408
- pcthrowaway 5y ago
  Please add this to the Twitter thread. I'm dying laughing at how true this is
thrashh 5y ago
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.
cogman10 5y ago
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.
- kbenson 5y ago
  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.
  - cogman10 5y ago
    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.
    - kbenson 5y ago
      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.
simonw 5y ago
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.
- marcosdumay 5y ago
  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.
eurasiantiger 5y ago
More like NEED-REFACTOR.CHECK-TODOS.CHECK-FIXMES
neilv 5y ago
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.plt&owner=dherman 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.
- ajmurmann 5y ago
  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.
  - neilv 5y ago
deleted 5y ago
[deleted]

andrew_ 5y ago

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.

mrits 5y ago

MARKETING.PM.ENG is closer to my experience

ithkuil 5y ago
Somebody should come up with a name for this and craft a manifesto on a website :-) Realver.org? Enterprisever? Corpver?
- dlor 5y ago
  Hah! I had something similar awhile ago: https://twitter.com/lorenc_dan/status/1209289792569131008 https://twitter.com/lorenc_dan/status/1209289792569131008
  - BeefySwain 5y ago
    I particularly love your followup: https://twitter.com/lorenc_dan/status/1209290259386769408 https://twitter.com/lorenc_dan/status/1209290259386769408
pcthrowaway 5y ago
Please add this to the Twitter thread. I'm dying laughing at how true this is

thrashh 5y ago

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.

cogman10 5y ago

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.

kbenson 5y ago
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.
- cogman10 5y ago
  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.
  - kbenson 5y ago
    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.

simonw 5y ago

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.

marcosdumay 5y ago
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.

eurasiantiger 5y ago

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

neilv 5y ago

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.plt&owner=dherman 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.

ajmurmann 5y ago
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.
- neilv 5y ago

deleted 5y ago

[deleted]