5 ms·
Minor Semver Issue
- gadilif 5y ago"While it can be easy to dismiss conversations around semantics, we need to keep in mind that communication is about influencing other people. If you use terms in an unexpected way, it will create a barrier making it harder or outright prevent you from influencing others and will likely add unnecessary frustration to all involved." This. In many cases people dismiss key points in an argument because "it's just semantics". But sometimes the semantics can be the heart of the matter.
- lmm 5y ago> If you use terms in an unexpected way, it will create a barrier making it harder or outright prevent you from influencing others and will likely add unnecessary frustration to all involved. We need to consider not just the literal meaning of a word, or its denotation, but also its connotation. > I believe the author was intending to say that some crate authors are not adhering to 100% of the semver spec. Article is being disingenuous here. The original author absolutely intended to call this a violation of the semver spec, with all of the connotations that brings. And frankly they're right: by "not adhering to" the spec, you break their expectations and break their builds. > With this continuous release model, what value am I providing users by bumping minor on all API additions? Most API additions end up being small and drawing attention to them with a minor release creates just as much noise for the user to sift through as patch releases. The rest of the article answers that: if you bump minor on all API additions, you allow others to specify a caret version with a minor version number, as the spec says they should be able to. Either follow the damn spec, or make it very clear that you're not following the spec so that we know not to use your libraries. Certainly don't try to blame other people for being rightly annoyed that you've made more work for them by violating the spec for the sake of what seems to be essentially your personal aesthetics.
- epage 5y ago> Article is being disingenuous here. The original author absolutely intended to call this a violation of the semver spec, with all of the connotations that brings. This is assuming intent that wasn't there. At the time, I did not know the author's view was so extreme that they view bumping patch on api additions is equivelant to bumping minor on api removals. I was giving the author the benefit of the doubt. I still feel discussing whether the same language for describing both is appropriate as I assume there are enough of us unaware or that don't care about the patch handling that it it is misleading to equate them. > The rest of the article answers that: if you bump minor on all API additions, you allow others to specify a caret version with a minor version number, as the spec says they should be able to. The spec says nothing of version requirements. If you are trying to say "you can accept any patch", thats not true. The semver spec says you can add functionality so long as the API is unchanged. This is setting aside relying on bug fixes which is frequent enough.
- jph 5y ago> Is adding a function in a patch release a violation of semver? Yes. When you add a patch then increment the semver patch version number. When you add a public function then increment the semver minor version and reset the semver patch version to 0. If you're doing something else, then you're not doing semver, and IMHO you should highlight that to your users.
- ReleaseCandidat 5y ago> Yes Only if your version is greater than or equal to 1. Before that, you can do what you want. Major version zero (0.y.z) is for initial development. Anything MAY change at any time. The public API SHOULD NOT be considered stable. https://semver.org/#spec-item-4 https://semver.org/#spec-item-4
- ChrisSD 5y agoIt should be noted that Cargo (the Rust package manager) has slightly stricter requirements here: https://doc.rust-lang.org/cargo/reference/semver.html https://doc.rust-lang.org/cargo/reference/semver.html > Initial development releases starting with "0.y.z" can treat changes in "y" as a major release, and "z" as a minor release. "0.0.z" releases are always major changes. This is because Cargo uses the convention that only changes in the left-most non-zero component are considered incompatible. This makes it more useful for OSS that never seem to reach 1.0.
- ReleaseCandidat 5y agoBut `can treat` is not a requirement but a suggestion. This is exactly the same as semver's 'all bets are off'.
- pornel 5y agoIn Cargo it's not merely a suggestion, but actual implemented behavior. Cargo takes the first non-zero number as the major incompatible version, and this influences dependency resolution.
- ReleaseCandidat 5y ago> The original poster insisted on using the phrase "violation of semver" to describe this scenario. It would be helpful in understanding what this post is about if this would have been linked somewhere in it.
- bayindirh 5y agoI think the whole blog post is floating in the air, because it's detached from all surrounding discussion and core event itself. It reads like a rambling at this point.
- ChrisSD 5y agohttps://users.rust-lang.org/t/psa-please-specify-precise-dependency-versions-in-cargo-toml/71277 https://users.rust-lang.org/t/psa-please-specify-precise-dep... Essentially there are a few popular Rust libraries that add functions in patch versions (or have done so in the past). This makes it necessary for users of that library to include the patch number when specifying the minimal version that they need because they can't assume an earlier patch will include all the functions they use. The original forum poster said such libraries were in "violation" of the semver.org spec. This blog post disagrees on using the term "violation" because this is a minor issue (no pun intended... or was it).
- epage 5y agoI wanted to keep the focus on the idea and not have this be viewed as an attack on the person. However, the person has gone on to more publicly talk about their views (the linked users post) so its more clear who I was responding to so I'm willing to post the original discussion (look for the collapsed posts): https://github.com/killercup/cargo-edit/issues/126 https://github.com/killercup/cargo-edit/issues/126
- Jenk 5y agoPeople who don't follow or understand the semantics of semantic versioning find themselves having difficulty with the semantics of semantic versioning. Next on News At Ten, we ask "Is the Pope Catholic?"
- twic 5y agoThe distinction between minor and patch in semver appears untenable to me. Say 1.1.0 adds a new function, and 1.1.1 fixes a bug in an old function. I write some code which uses both functions, and would hit the bug before 1.1.1. This code has to be used with >=1.1.1, or it won't work. If it's used with something <1.1.0, it won't compile, and if it's used with 1.1.0, it will compile but not work; the distinction between those clearly isn't significant. So in practice, 1.1.0 -> 1.1.1 is as meaningful an increment as 1.0.0 -> 1.1.0. Semver would have been better with just major and minor versions.
- Karellen 5y agoYou might not actually hit the bug in the old function. It may be that the function only has an error if the caller passes `argc = 0`, but there's no way your code will ever call that function that way. Bug fixes tend to be for weird edge cases. If the normal functionality doesn't work, someone would probably have noticed for the 1.0.0 release, or at least before the 1.1.0 release. And most of the time callers not only don't hit, but will never hit, the weird edge cases - that's what make them weird edge cases. That said, given enough users, Hyrum's Law comes into effect where not only do some small percentage of users hit your weird edge-case bugs, but a small percentage of those end up relying on them.
- ergl 5y agoIf the maintainers have a good back-porting policy, they'd also put out a new 1.0.X release so that users of <1.1.0 can upgrade and get the fix without also getting the new function in 1.1.0. This is something that Apple sometimes does for security updates on macOS: they'll release a new patch version on all supported versions.
- epage 5y agoI feel minor vs patch is useful for communicating and for the psychological effect. Most people won't care about adding a stray function for one person. Major new functionality is different. Yes, this mixes "sentimental versioning" in with semver. People tend to rate limit their major and minor versions, waiting until they get enough changes to "justify" it. While this can have a negative effect for small additions, I think its good to rate limit deprecations which are important for minimizing the impact of breaking changes.
- Arnavion 5y agoUntil `-Zminimal-versions` gets stabilized this problem will never go away. The ecosystem is too big to be able to get everyone to coordinate unless the tooling enforces it. I'm in the `serde = "1"` camp myself, even though I know that I "ought" to be doing `serde = "1.0.whatever-versions-docs-I'm-reading-right-now"`, but I don't because that's not right either. If I start a new project today, open the docs of serde and see that it's at v1.0.100, sure I could write `serde = "1.0.100"`. But then when I open the docs the next day to look up another function to use, and serde is at v1.0.101 now, does that mean I have to defensively bump it to 1.0.101 now? If that was the case then every code commit will involve bumping every dependency constantly. The only way this can work is if my local build / CI compiles with `-Zminimal-versions` and actually tells me a certain version is wrong. (Note that even for nightly users, `-Zminimal-versions` is unusable because it also applies to transitive dependencies too, so you're at the mercy of your dependencies specifying their dependencies correctly, which none of them do.)
- pornel 5y agoCrates don't add new APIs every day, but if you allow a revert to a 5-year-old version, there will definitely be an API difference. I know that without testing you don't know which version exactly is the right one, but it's safer to err on the latest side, than the oldest side. Serde specifically had an issue with exposing and renaming some APIs that were meant to be private and got used in other crates (let's not even get into how that relates to semver, and whose fault was that), so IIRC serde 1.0.123 is the lowest version you can safely allow these days.
- epage 5y agoI've traditionally done the same out of laziness. `cargo add` being merged into cargo (soon) will remove some of that laziness. This does make me interested in adjusting `-Z minimal-versions` to get it useful. The biggest problem is depending on all your dependencies to be good citizens and test it (some refuse) or patching your deps (I'm too lazy). There is an idea floating around to make it only apply to your direct dependencies.
- gspr 5y agoAt least the Rust documentation system makes it very easy to just switch to reading the 1.0.100 docs also in the future.
- simiones 5y agoSemver always seems utopic to me. Unless I've tested my code with a version of a library, I can't know if it works. Even if they are religiously following Semver, there is always the possibility that they have a bug that happens to affect my library. Automatically picking up some library versions based on a hope that people adhered in the same way to Semver and that they don't have any bug-level incompatibilities seems highly optimistic. This is one of the main reasons I hate this trend of small libraries: I don't want to have a complex web of dependencies that I am the first person to ever test in this particular version combination. Give me Apache Commons any day of the week, with a single unified version for hundreds of classes that I know for sure work together among themselves.
- tikkabhuna 5y agoI like Semver. Not because it guarantees that a minor bump won't break anything, but that the maintainers expect it shouldn't. If I need to bump a version with Semver, I can estimate how long it will take. Going from log4j 1.2.17 to 2.17.1 will be bigger than going from 2.16.0 to 2.17.0. And 2.17.0 to 2.17.1 should be easy. I completely agree with your last paragraph, though. I'll take a collection of utilities from a well known organisation over many tiny dependencies any day.
- simiones 5y agoAbsolutely, Semver is a good idea as a way of organizing your software's versions. But basing your pacakge manager on the specification of Semver seems like a bad idea to me - though it is extremely popular in the industry currently (NPM, Cargo, go mod, and others support it).
- WorldMaker 5y agoIt's tough to remember that the "sem" in "semver" stands for "semantic" and implies "meaningful to other software developers". I understand why we like to try to automate it, but aspects of it were intentional rejections of automated version numbers in the first place and it feels like a cycle of automating things, finding failures in them when automated, and trying to remind ourselves why we shouldn't just automate every aspect of our jobs. Sometimes you need the "semantics", the human judgment calls.
- pictur 5y agohonest question: have you ever worked in a place that really pays attention to versioning?
- epage 5y agoGenerally, they haven't. The most I've seen is using pre-release to communicate between teams when a shared dependency is ready to ship. In the Rust community, there is tooling and culture around Major that we pay attention to that. Otherwise, I've seen no one care about minor vs patch until now, which is what led me to write this post.