Is Semantic Versioning an Anti-Pattern?
surfingthe.cloud
surfingthe.cloud
> 1. Software using Semantic Versioning MUST declare a public API.
That's the very first thing it says. Semver is not meant for general apps or websites or the like, it's for APIs against which dependencies can be declared.
If your software doesn't need to tell package managers about its compatibility, then it doesn't need semver. Complaining that semver is bad for human readability is like saying hammers are an antipattern because you don't use nails.
When only nonsense is written against an idea, it's great , it shows the idea is great
If you write a project in rust, for example, you must give it a semver number in your cargo.toml. You can give it one that makes no sense and maybe never change it or change it arbitrarily, but the implication of that field is always that it's semver. It's right there in the docs: http://doc.crates.io/manifest.html
This is a real procedural problem that is being created by a "silver bullet" approach to versioning that the semver people can deny they're trying to create, but is happening anyways.
If you share code you should use semver, because someone will (hopefully) import it and use it, and it communicates your expectations of stability.
I worked at Amazon for 1 year. They use semver for everything. I think that's one of a few technical superiority I missed since left. I am curious about its problems.
The article did not say much. As for the suggestion given in the article, I cannot help to think that one can always release a number based on a semver to external customers. That does not prevent semver being used internally at all.
> a general trend towards literally forcing things to adopt semver
This statement assumes that semver is bad if forced universally, which may or may not be the case.
Your comment include no fact that this is bad. When you mentioning rust, you also did not say anything why semver is bad.
I mean, if someone put an arbitrary number there, and users are screwed because of author fails to maintain the correct contract, at least people can go to there and point out that the contract is broken. Removing semver does not do anything good. It just give the author an possible excuse, i.e., if users are screwed, the author can claim that he/she never meant to make its software backward compatible. For that, semver also provides the same mechanism, i.e., bump a major version number. At lease users know that they can expect a breakage.
Our release version numbers are literally jenkins build numbers. Anything else is not worth the administrative overhead for our needs (even were that 'small', it's also weirdly political in a bikeshed sort of way).
And I don't think this is really all that uncommon even for higher level things. I don't think semver makes any sense for a rails app, for example, but in rubyland you only version things you publish. Rust makes you version things you will never publish.
Don't get me wrong. For the things we consume from outside our team or abroad, semver is an absolute boon. Sometimes, though, when you point out that people are treating something as a silver bullet, you're saying it's outright bad. I'm not saying that. It's not a problem with semver that semver is not universally applicable.
The nice thing about version numbers such as Semver is that whenever you do need to maintain more than one branch of your library/tool/application, its just a matter of branching the code, and assigning a higher major version to the newer branch, whilst keeping the older major version for the stable older branch (which will still receive fixes).
With build numbers you lose a way to distinguish these two, with Semver you have an old branch (v1.0.0, v1.0.1, v1.1.0, …) and a newer branch (v2.0.0, v2.0.1, …) that can both receive new updates and version numbers. Because you usually can't predict which internal project will by necessity get split into two parallel development branches, you might as well just use version numbers everywhere.
I don't quite get the administration argument you mention. A lot of modern build software (Rust is mentioned, but Java does this as well with Maven) use some sort of versioning to facilitate this out of the box, so why go out of the way to not use them?
Version numbers seem to exist purely so proprietary vendors can obfuscate their source code a bit.
If I have the commit hash I can go straight to the exact source code version.
Taken to its logical end goal, really I want three things: commit, upstream branch, and where to find the code.
With those 3 and a little bit of tooling I should be able to go from a version number to the commit log of the current compatible upstream (I guess I'm implying a branch == backwards compatibility but just getting the commit log of really what I want)
We don't need semantic versioning in open source - we need a common immutable web which lets us search on the things which matter.
Just the SHA1-hash makes this all needlessly opaque — I'm a human, not a machine.
> Version numbers seem to exist purely so proprietary vendors can obfuscate their source code a bit.
Whatever makes you think that? From what I have seen free software projects tend to apply their version numbering schemes with a lot more reliability than proprietary software vendors. And of course version numbers don't obfuscate; any developer worth his salt using version numbers will tag the corresponding commit in the source code repository, and any build environment worth working with will provide a 'release' command that does this automatically.
Whereas again, what you and I are both saying is "who cares, I want the commit".
Commit + Branch means I can answer the question "is my problem fixed (or are things broken) in the newest version of the code" - which is the actual question semantic versioning proposes to answer but can't.
Adding a release number for human readability is fine (i.e. imply some quick ordering so you can go "oh, this isn't the newest version"). But even then: when putting together systems, that's not a question I ever really find myself asking - the one I'm asking is "are these things exactly the same, and what's the latest I can upgrade to without breaking it (or conversely: which was it working fine on).
Which is why I point out the need for an immutable web at the end there: if we accept version ranges are useless for doing reliable ops work (I believe they are - i.e. you will be testing everything anyway), then in order to know anything about what does and doesn't work, I need the source code and commit logs. I probably don't want to include all of those in every release and I do want to be able to get to new versions, thus the three things I need: upstream location, upstream branch, and commit hash. Everything else is irrelevant, or sugar.
EDIT: And we can derive simple ordering numbers anyway - just count commits on the release branch since the product started. Accomplishes the same thing.
EDIT 2: It's also worth considering though, that incrementing numbers introduce subtle bias - people always want the highest number, and assume it must be better. There's always an urge to upgrade to version 2, even if version 2 might be a complete rewrite and less developed then 1 with an uncertain future. How different it might be if we only talked about branch names and commits - we're on the "beach" branch, but the company has a got a new one for the product called "forest". How different might discussions about "upgrading" be, and consideration of security fix deployment and status.
I (not the grandparent poster) usually don't just want the commit. I want to be able to look at two versions and have a good idea if they're source and/or binary compatible.
If I do need to deal with the source of the app, hopefully they're doing me a solid and tagging commits with the version number.
> Commit + Branch means I can answer the question "is my problem fixed (or are things broken) in the newest version of the code"
Sure, if you want to sift through a VCS log, which I don't want to do. I want a changelog file that tells me what's in the version I'm running, and all versions previous. That answers that question too, and maintaining a changelog (even if you just dump the output of git's shortlog into it every release) is just a responsible part of release engineering.
> ...which is the actual question semantic versioning proposes to answer but can't.
No it doesn't. Semver exists to help answer the API/ABI compatibility question. It has nothing to do with whether or not your bug is fixed or not.
> No it doesn't. Semver exists to help answer the API/ABI compatibility question. It has nothing to do with whether or not your bug is fixed or not.
But it has everything to do with whether other things are broken (i.e. incompatible) which is what determines whether I can upgrade or need to triage. So yes, the question is "whether my bug is fixed and I can use the fix".
The problem is compatibility is a useless theory when you actually need to deploy to production - it either works or doesn't, and if going from version 1.0.0 to version 2.0.0 requires the same amount of testing as going from 1.0.0 to 1.1.0 then I don't know what's been accomplished. Same story with changelogs.
Either way, requiring semver formatting here sounds like its entirely justified.
Let say you create a cli tool, with a given set of command-line parameters. These parameters are the API your programming is exposing. I can use your program from a shell script for instance, and I will use the existing interface. If, in the next release, you change the options your cli program is accepting, you are actually breaking compatibility with existing integrations including my shell script. Hence this is a breaking change and you should upgrade the major version.
edit: Oh I see. I can see how you'd interpret what I said as implying that [all not libraries] are terminal. I wasn't being exhaustive. :)
Java build tools are also built on top of versioning.
rustc won't ask you anything about version numbers.
So that just leaves toys :)
Also, btw, even though I'm saying something vaguely negative about cargo I love that both rust and cargo exist and I've been aware of the work you've been doing since your rails days and always liked what you've done and had to say. Just thought I may as well throw that out there. :)
I didn't even take it as negative, to be honest.
The benefit is that you get the object ID along with an automatic counter of the # of commits since the last tag, which is basically a nice, automatic version number that you only very rarely need to update (by creating a new tag).
$ git tag -m'app v1' v1
$ git describe --first-parent
v1
# hack hack hack
$ git commit -m'subsystem: some new feature'
$ git describe --first-parent
v1-1-gab2fcd9
# hack hack hack
$ git commit -m'subsystem: some other new feature'
$ git describe --first-parent
v1-2-gc37ed42
some-library>=1.0.0,<2.0.0
It means I can include a library and get non-breaking changes and all security updates until the next major release without worrying that a change is going to break me randomly. It doesn't mean I don't need to do testing, but it makes it a lot more likely that I won't accidentally break in some way I didn't expect due to a change upstream.
When I want to upgrade to a breaking change release I know I need to go look at the release notes to see what the breaking change is, and then make modifications to my application.
If a breaking change is made in a minor or point release I can open a bug with the project so they can revert this change in the next minor or point release.
(edited from <=2.0.0 to <2.0.0, as this was my original intent :) )
/me displays closet full of T-shirts.
some-library>=1.0.0,<2.0.0
However, that your issue isn't a problem with SemVer, but a problem with NPM/node. SemVer is working as intended, but getting the "secret sauce" to get everything working can be confusing as you try and figure out the differences between "devDependencies" and "peerDependencies". If every module just managed their dependencies, it could be easier (on your development experience, but not on your hard disk and build times).
It does. Semver implies semantics arbitrary versioning is not.
That's what .lock files are for.
This doesn't prevent the use of version ranges during development or testing.
Edit: To be clear, I do not work with Node. If this is standard practice for Node shops, that's terrible.
Not taking security patches is bad. Taking down production is also bad.
I won't say it's ever good, but for most software some downtime isn't the end of the world, certainly better than having security exploits available.
I'm not saying that view is necessarily good, but I think it's common. I also think it's quite common that people assume this is the client view and act accordingly.
I definitely think skipping testing with the goal of getting security patches out sooner is a terrible plan except maybe in the case of an active exploit. You can get both frequent patches and high availability.
This discussion is based on a false dichotomy. Yes, shops can be bad at updating dependencies. That's a matter of culture. Technically, I shouldn't have to constantly scan my dependencies for updates, much less security updates. That's what CVEs and release notes are for. Not freezing the dependency tree in CI and production on account of security updates is a bad pattern.
Nodejs is the first time I've encountered a deployment problem whose resolution was "you have to upgrade your package manager to a beta version".
You know, this should be a hint that the problem is perhaps not with the versioning system.
That's not how you're supposed to use npm. You should never perform an npm update directly in production exactly because of what you describe.
The proper way to manage dependencies update in npm is to perform the dependencies' updates in your build process when building your pre-production/staging build and then use the shrinkwrap[1] command of npm to generate a file with all dependencies pinned for production. This way, for a given production deployment, you know exactly what version of which dependencies was being used and you can rollback easily if an update break something.
semver is useful even if you're releasing something that isn't a library because it can be used to provide information about backwards incompatibility in things like database schema, cache incompatibilities, configuration file incompatibilities, that'll cause a service to break if updated.
Well, if you release a ton of versions of your API, some of them are going to be easier to transition between than others. As soon as that occurs, you conceptually have at least major and minor versions, but in a url-based API instead of in code. Or you choose to not hint your consumers if moving from v23 to v24 is likely to be simple or not.
[1]: https://surfingthe.cloud/ideal-api-versioning/ is mentioned in the article, for example.
Which is true. But then why even bother with YYMM.xxxx? Just use a single incrementing integer. Or none - nothing can ever go backwards, so callers are required to ignore the version in practice.
[1]: an API presenting an old external interface is something different - there's still only a single "version" of the code that's actually running.
I personally dislike using semvar for these instances (my own opinion only) because it feels overcomplicated as you stated. I also learned a long time ago that _any_ kind of date designator was a recipe for answering why the "April" release was actually live on June 1st ;). Recently, I've dropped back to Git SHA-1 which has alignment to a specific version of code released AND can be tracked by date and deploy tools.
So I agree with the thesis, disagree with the solution, but still think ryan_lane did not effectively refute it above.
I pretty much exclusively deal with SHAs too, since tons of tooling understands it, and there's no implied order just by looking at it - which is a good thing. A SHA might be out, but waiting to ramp up to 100%. It does tend to mean "end of (nearly) all dev work" though, which is the actually important part for day-to-day developing.
By and large, especially in an org, if you make a change that requires another place to change, you should go ahead and make that change. Period. Thinking people can stay on the old version till they want to update is BS. They will update when they have to. And it is rarely easy, then.
A good solution to this is to have an "edge" build that will upgrade dependencies and let you know about breakages early, but that still requires companies to acknowledge that all software needs maintaining.
I bet semantic versioning is mostly championed by older veterans who have worked in maintenance or systems administration roles and are trying to get the industry to return to a versioning system that made sense once upon a time.
For my part ... while I'd dearly love to see semantic versioning come back, along with a few other good habits from a long time ago, I've given up on that and now just accept that updates will break things sometimes and there's always something to update and so something will be broken most of the time and that's just how it is so charge accordingly.
But we used to pay software vendors a lot of money to care about boring things like backwards-compatibility, legacy support, and etc. Semantic versioning as a standard is a way of applying social pressure to authors to do the 'dirty work', regardless of whether they are being paid to do so. And if they don't feel like it, the result is usually "too bad for you". There's no real good answer for this that I can think of. Nobody wants to pay for leftpad.js Enterprise Edititon.
That is, the version scheme States the point is to somehow be in a position to get only security updates. However, unless there is an org specifically for maintaining a library, your only hope of getting updates is to take all updates. So, to stay on the latest.
Which just highlights, to me, that semver is ultimately good intentions masqueraded as a mechanism.
> the lie that people will do security and other updates on older versions.
Semver does not say anything will be supported. You still have to know what's going on with your dependencies as far as big releases and patches go. It simply says that is old versions are still supported, they're updates will preserve compatibility.
With c/c++ additions can break binary compatibility can't they? Adding a field to a struct for instance will mean existing code that does a malloc for that struct won't allocate coorectly. I think there are a million other cases to consider too.
I think semver covers this pretty well actually. The public API is not just the function signatures, but basically anything that makes your API - whether it's code or documentation. So either:
- your structs in the library are opaque and the library handles all the memory management itself - addition of fields is backwards compatible, or
- your structs are open and your functions expect the structs from outside - addition of fields is not backwards compatible
The second one is still falls under "Major version X (X.y.z | X > 0) MUST be incremented if any backwards incompatible changes are introduced to the public API."
To make a comparison in a dynamic language: you've got public function `f(d)` where `d` is some dictionary with elements `a` and `b`. Now in the next version you start to require `c` - same signature in the code, but it's not backwards compatible. It's still a public API, even if defined by the documentation.
What about c++? Object allocation is always handled by new on the consumer side isn't it? Also in C, does the order of function declarations matter?
And no, after compilation, I don't believe the symbol order matters.
It's also an issue if very performance-sensitive routines need to read data from the object. In which case they already know exactly what's in there, so "pimpl" hiding has no benefit in the first place.
Implementations should be hidden if they are likely to change. In other words, there are are non-obvious data or method members and/or it's likely that functionality will be added in the future. These are the high-level architectural situations, not the leaf level ones where you optimize out every cyle possible.
Sometimes it's possible to handle this case (if you've planned ahead) by including unused space within the original struct defintion that you can then repurpose later.
It's hard, but certainly not hopeless.
glibc uses it extensively, but alas few other people know about it. Theoretically languages, like Rust, which compile to ELF executables could leverage the capability. But none do.
There are a series of posts from a libvirt developer which explain some of the mechanics:
https://www.berrange.com/posts/2011/01/13/versioning-in-the-libvirt-library/
I don't begrudge people using semantic versioning, I don't just don't think it's the best approach for most cases. It's just one of several crappy choices. But at least with C on Linux, ELF symbol versioning is a slam dunk when you're serious about the matter.
[1] I usually avoid depending on proprietary platform features. But this is the one area I'm comfortable and eager to lean on Linux.
Really? Do you ever call `malloc(4)` instead of `malloc(sizeof(int))` or `malloc(sizeof(*ptr))`?
Surely they're mutually exclusive terms. I think GP was talking about cases where the developer releases a change thinking it's just an addition, but it actually breaks compatibility.
Of course, that boils down to saying that software updates sometimes have bugs. What that has to do with semver, I have no idea.
I think others covered the edge cases where additions literally break. The sibling that said I was likely referring to just plain bugs hits it pretty well, I think. I was not going for esoteric scenarios.
And yes, semver doesn't say anything about if a version is supported. However, it is a strong indication that it is. In a social expectations sort of way. If you don't plan on supporting old versions of what you are doing... use a new name for the new stuff. Nobody expects google guava to support apache commons, even though they are doing a lot of the same things. We do expect, however, that apache commons will make sure any bugs in old versions are dealt with.
counterpoint: rails. At least two versions are supported at any time, sometimes older versions still receive fixes for critical security issues. Rails follows semver and they're doing fairly well. I rarely see breakages from upgrading anything but major releases.
For a larger org, it's basically impossible to do that if you want to make forward progress.
But very much agreed that it's usually not easy to upgrade farther down the road when many things have changed. I've been trying to spread a culture of forethought and not changing things for the sake of "making things pretty", but it's an uphill battle.
You can just about get away with this within an organisation, but you cannot do it to your customers if you have a competitor which doesn't impose this workload on them.
I'd like to kill off a decade-old toolchain I have to target, but people are still using the hardware it's required for. They don't want to spend the money on replacements when the current hardware still works, and why should they?
No, no, no, no it isn't great; it's terrible.
It's makes the version used non-deterministic, and that is a recipe for build hell. The whole reason we have lockfiles, shrinkwrap, etc. is because people are specifying version ranges.
You may lock library versions for a build pretty strictly. But the more loose is the coupling, the more elbow room you have in this regard, so you can upgrade your ngnix without breaking your wsgi apps, or your database without breaking anything — when done within a reasonable range of versions.
Let's just say it: a lot of web development is done by producing a blob of code and frameworks of the week, getting paid, and not caring about security and maintainability.
The poor practices and tooling are a consequence of this mindset.
Libraries should depend on ranges (though they can also pin internally for development).
Anyone deploying an application to a server or distributing an application to end users should have the dependencies shrinkwrapped and the application tested with them.
Upgrading dependencies to get bug and security fixes in minor and point releases is as easy as deleting the shrinkwrap, installing the dependencies again, and making a new shrinkwrap. Then you put your application through all of its tests with the new dependencies, commit the new shrinkwrap, and then you can release/deploy a new version of the application.
Having a non-deterministic version, so you can easily upgrade all your dependencies and get the latest and greatest compatible version of everything, is great.
Even the smallest and most stable change can break backwards compatibility or fix a bug or add a new feature and semver's only purpose is to meaningfully express what kind of change it is. You build a 3rd party package or a library which is used by other people? You better use semver. It makes everyone's life easier and not more difficult. You build some REST API which is consumed by other applications? You better use semver. It not only helps to visually display what kind of change it was, but it also triggers an additional thought process during development and CI. For example if the major version doesn't change, then the CI system can reliably replace the existing API during the deployment process. However when the major version changed, then you might want to think about a side-by-side deployment to support backwards compatibility, at least for a certain grace period. It makes life in many ways easier.
And again, this has nothing to do with how stable a release is. Let's say I have a public facing REST API and I make a 1 line change where I decide that some field of a JSON object must be int64 because in some edge cases an int32 wasn't unique enough and would have caused a bug. Now this change is fixing the system, making it even more stable but essentially breaking existing integrations. Semver helps me to easily communicate the change to my API consumers, setting up the right expectations and helping them and myself by reducing frustration, tech support and unwanted side effects. It also helps to deploy it in a way that allows a smooth transition to the newer API.
Furthermore his suggestion of using a date is useless. What does a date tell me? Nothing... if I want to know the date I right click the files of a build and look at date + time or I look at the commit time in git or the build time in the CI tool. Having it in the version is stupid.
This i care about.
> fix a bug or add a new feature
Not sure why i should care about these tho.
> essentially breaking existing integration
Not sure why you need 3 numbers to express that. Am i right in that your consumers dont get bugfixes by default because api patch version is changing? How is this working irl?
> suggestion of using a date is useless
Dates are just easier to scan by humans that just monotonically increasing numbers.
>> fix a bug or add a new feature
> Not sure why i should care about these tho.
>> essentially breaking existing integration
> Not sure why you need 3 numbers to express that. Am i right in that your consumers dont get bugfixes by default because api patch version is changing? How is this working irl?
But it would work the same way with monotonically increasing version. no?
> When you fix a bug you increment the patch version
I am just trying to understand how semver applies to REST in your case. Never seen anything but single number versioning for endpoints.
> But it would work the same way with monotonically increasing version. no?
> I am just trying to understand how semver applies to REST in your case. Never seen anything but single number versioning for endpoints.
I work on a platform team developing many different libraries used by many different teams throughout the company. If we didn't leverage semver (or some versioning scheme that at least differentiates between breaking and non-breaking changes) I don't know how we would do it. We either a) wouldn't be able to release 'patch' updates to a particular library without consumers getting it for free/automatically without changing anything or b) wouldn't be able to release breaking changes without it automatically breaking consumers builds.
Semver may not be useful for the final build or end product that you end up shipping. But it is a very useful tool for all the parts (dependencies) that make up that final product.
For programming languages it is less clear to me that there are benefits. The same goes for living production end-services, which are the topic of the article. Said production system might (should?) be separate in version churn from any API built on top of said system, or client libraries used to interoperate with said API.
It is likely that I agree with Mr. Gillespie on the topic with respect to "always on" systems, but I do not feel strongly about that agreement? I tend to look for and focus on Semantic Versioning in its sweet spot, that is, libraries.
Having said where I agree, there was one quote of the article that stood out to me:
>it feels a little bit overly pedantic
In my experience, that's the best part, perhaps even the entire point, at least with libraries. Semver is just a method of communication, but its standardization and lack of ambiguity (relative to other systems), means that communication is all the more clear. I need a new feature and so am bumping a library to a new minor version? I'll be sure to check for other new things and for any deprecations, but won't need to worry that existing behavior was removed. Very clear.
When I am engineering a system on top of various libraries/tools, then growing and changing said system over time, I want to be able to pedantically assert what is known (as well as what is not known!) about the system's dependencies. Semver is a good tool for this job.
Previously discussed: https://news.ycombinator.com/item?id=13085952
Your comment is dead, but to answer the question - the alternative proposed is to encode the contract of your library in itself, and never break it, only extend it.
If you need to change the API, you don't change behaviour or signatures of your functions while preserving the names; you just add a completely new mainspace, while letting people use the old functions if they still have reason to. You don't have to keep actively supporting the old namespaces (i.e. no new bugfixes), but just need to not break the stuff that already worked.
There's some scenarios where this is hard - for example it's a web api and supporting it is costing you $$. But for things like that devs are generally aware that what they're consuming might get shut down at some point; so doing a new api, in a new namespace, and shutting down the old one at some point is not completely out of the question.
However if it's just software for the end user, such as a web browser, it doesn't make as much sense, what is defined as a breaking change for someone browsing the web? And will they care? I've seen it be used for websites, ok great, but who's on the receiving end of these version change numbers? At the moment everyone is trying to do semver even in situations when it's not needed.
Also, for corporate customers it is sensible to agree on the version range supported for a web browser if you are offering a SaaS solution, especially if security matters.
"That version has Flash, that version does not; doesn't make sense to the user to tell them apart." Riiight.
If you are developing your own personal website with a static page and bootstrap, probably over kill.
We don't need to have a polarized opinion about everything.
If you're some pissant shop writing CRUD apps then yeah, don't bother. As soon as you outgrow that stage, there won't be any more questions.
Monolithic standalone apps or tiny projects don't need semver. Practically all collaborative software in between benefits massively from it.
Semver is all about creating reliable builds from dependencies.
What. No, that doesn't follow at all. This is the equivalent of "hate leads to suffering".
Just increment the last number on each deploy. X.Y.123456789 is perfectly acceptable. Or if that strikes you as a distasteful abuse of the "patch" value, add another layer to get X.Y.Z.12345689. Semver systems will be perfectly happy with a 4 layer option, because none of them are stupid enough to be useless when handling edge cases.
<rewrite number>.<release number>.<commit number>
- 1.0.0
- 0.1.0
.....
- 999.999.0
With this you get the following:
- Is this stable to use in production.
- What software can work with what other software (looking at the major version it requires)
- Between which two commits a functionality broke. (If 1.1.157 works and 1.1.158 doesn't then you know commit 158 broke something)
- The month, year and # of commit you're on
- If someone else gave us this code (pr-)
- If there is active development on the code (dev-)
The only purpose of SemVer is to express whether a change is breaking or not. It fails at that. Nobody can predict whether a change is breaking. Because code is complicated, and code with dependencies is exponentially complicated.
At best SemVer communicates from one human to another the _expectation_ about whether a change is breaking. The expectation can, and frequently is, broken.
All changes are breaking changes. Vendor your dependencies by hash. Humans cannot be trusted.
I really enjoy how the package-manager for the Elm programming language automates semantic versioning by diffing your apis based on the type system.
I think a bit part of the real criticism of SEMVER stems from this inability to either automate it or use it correctly.
Hickey's discussion of the subject obviously has a lot more great points to it, and even when I don't agree, I can't help to enjoy listening :)
Can you name a package management tool that doesn't rely on SemVer?
In any case, none of the things you use SemVer for are Continuous Delivery always-on production systems. They're software releases.
CD is good for code you control. But for your dependencies and platforms it's the opposite. Just imagine CD of kernel patches right onto your production servers. Or CD of Java updates (or Python or whatever your app is powered with). And guess how long your system will stay "always-on".
I was very disappointed to learn that Italy did not, in fact, elect a Shiba Inu to office.
Enterprise software sells for even more money, and the above is even more true, usually backed up with lawyers, PR campaigns, etc.
Windows 7, 8, and 10, sound to the average person more reasonable that:
(from the article): 1612.0009, 1612.0013, 1701.0253
Thus, they are not only a rock solid pattern, they are the bloody unwritten standard and more so everybody's daily expectation.
I agree that an average user only cares for the major component.
[1] https://www.reddit.com/r/haskell/comments/5iok3l/haskell_pac...
foo-lib >= 1.0, < 2.0
I will always update to the newest 1.X.Y version of the foo-lib.
This is not the case, such pattern can silently install one of the older 1.X.Y releases due to the requirements of other libraries that my software uses and that are out of my control.
This is pretty dangerous, the pattern treats all 1.X.Y as equally good for me, but X and Y updates can contain important, often security related bug fixes.
A safer way would be to be able to say: I want to have the newest 1.X.Y, fail if it is not possible, so I can investigate.
If you need a version and don't care about following the spec just use a timestamp or datetime, replace it where required with a sed command and move on but please don't claim to use semver if it's just an arbitrary number for you
Minor versions are things you reasonably might depend on like a new feature or significant bug fix. You _should_ be able to upgrade seamlessly though one person's bug fix is another's breaking change. I don't think it's reasonable to get rid of these and treat everything as a breaking change.
So I don't know what's simpler for libraries. Semver seems to have boiled it down pretty well.
Three-part is unambiguous.
When both those pieces of information - backwards compatibility and the need to upgrade - are important, semantic versioning should be used. If you are comfortable removing features without leaving an out for users, and you can reliably upgrade all users at the same time, encoding this information is much less important.
That said, a three part number isn't really useful. Just increment the minor version number in all not incompatible cases.
Also, there is an antipattern with releases, it's naming them. It's complete bullshit because opaque with rarely any rhyme or reason. It's branding plain and simple. If you need to upgrade anything, you end up having to googling what the actual version number or release history is and then going off of that. It's a complete waste of time, and so twee.
The article is just bizarre. It's like ranting about how knives suck because they can't easily transport rocks.
I find the right thing to do is to set up a completely parallel “beta flow” that mirrors production almost exactly, allowing you to freely dump in new changes and see what happens. Have a way to swap working beta-flow changes into production, and a way to swap it back. Then you can do anything you want in beta.
An easy way of knowing which versions you should be able safely update to without breaking changes seems hugely valuable.
He talks about APIs versioning, but APIs are only a small part of the problem. How about the hundreds of libraries that my site is built with for example? Semver allows me to specify rules in my package file about whether to take only the exact version that I want, the latest patch, or the latest minor version. I didn't spot anything in the article that showed a better way of doing that.
The problem of knowing whether 1.3 vs 3.7 was written 10 days ago or 10 years ago doesn't seem useful. Rarely has software I have written depended on how recent the library was released.
Ultimately, the talk tears into version numbers in general, but not semantic versioning - he doesn't discuss anything particular to SemVer. He could have been talking about Postgres' versioning conventions and the talk would still hold.
A) avoid breaking API changes
B) if you have to do large breaking API changes, that will probably affect alot of dependent projects, make it a new artifact / namespace / library that can live side-by-side with the old version
B is actually pretty common in large java library projects (rxjava -> rxjava 2, retrofit -> retrofit 2, dagger -> dagger ‡ all have independent maven artifacts and I think also packages) and imho this approach makes a lot of sense. It's also the more important part of this talk compared to his critique of semver.
I mean, it's not like people delete 1.3.0 from their packaging system when they release 2.0.0. Incrementing the major version number is semver's way of declaring a new namespace, and once declared, it lives alongside the old ones.
What is Hickey suggesting be done differently?
With that in place it is questionable what the actual advantage of semver vs a simpler monotonous versioning schema (like build number or UTC date) is.
He does talk explicitly about the trouble of making major changes in SemVer[0]. The gist of his argument was that minor changes in semver are relatively useless while major changes have a high probability of breaking your software. Major changes in semver are backwards incompatible and update the program's API in place. This leads to dowstream breakage and fear around doing upgrades.
> If I need to upgrade my application due to a security vuln, SemVer lets me know if I can just "drop-in" the upgrade, or if I need to work more.
I think the point he was trying to make was that upstream developers could change internals of a library but keep the API consistent so that downstream devs would never have to worry about scary updates. As you said with SemVer, if the security upgrade is a significant change, then you can expect breakage in the library. What he was advocating was patching issues like security vulns under the hood while keeping everything backwards compatible. Major upgrades could even add new namespaces, functions, and arguments but there's no real point to deleting or mutating old code, that just creates breakage. He wants software libraries to be immutable to take care of dependency issues and versioning to better reflect the changes made in the code.
[0]https://youtu.be/oyLBGkS5ICk?t=13m45s
In practice that's very uncommon. If someone is actually doing security releases, then either they release a minimal change to supported versions, or the distributions do that for them. Actual security upgrades are normally single patches which take great care not to do any API or behaviour changes.
Left unresolved is how to deal with the accumulation of old code. I assume there will eventually be automated ways of turning it into a library, so the old code no longer needs to appear in the code that you are actually working on. Some automated solution seems like the kind of thing that the Clojure crowd will come up. I think it would only take me a day to write a macro to recreate namespaces from a library. Zach Tellman has some code that does half of this (Potemkin).
But I want to argue one point: that versioning APIs would be simpler than versioning a component/lib.
If a lib exposes one API seperating the version numbers would result in two.
If we look at exposed API and differentiate by purpose (a good idea imho) we would have multiple version identifiers- one for each API and one for the component.
I thought about API versioning and testing (a special kind of unit test to verify the contract an API promises) but I don't think we are prepared for such complexity.
I prefer the first number to be a simple release number, then the second to be the amount of risk from the previous release. That way for projects with a dozen or two releases one can normalize the risk values between projects to get everyone more or less on the same page without them having to change their behavior and it can introduce the ability for you to manually correct the risk for different libraries (eg: Library X is super critical for me, so *2 the risk).
Automated tools for calculating risk are possible with this scheme and additional risk can be added for the update (eg: tool sees you are using method X or API call Y that was changed, so the risk is increased).
With release.risk you can say "Automatically update when total risk is <X" and actually have it be tolerable to you. Even when manually updating, you can get an idea of how much trouble its going to be, and possibly have a tool generate a list of areas you should put extra attention towards (eg: library X has a risky update, check to see if it breaks your corner cases).
As I understand it, all semver is trying to tell you is when backwards-compatible changes happen, and when backwards-incompatible changes happen.
If the project developer wants to add some sort of indication that "this package contains changes that are alpha quality, and may not respect semver for the next few releases" then that developer can append a pre-release identifer to the version, as described in the semver spec. Once that identifier goes away, the risk that a package violates semver should be gone, and you should be free to update based on the semver relation to the previous release.
Ultimately, it's up to the project to verify that their releases don't violate the semver spec by being diligent with respect to their public API. If you find that a project isn't disciplined in documenting API changes (semver or otherwise,) then coming upw ith new rules to convey the information they're already not conveying isn't going to help anything.
For example, a change in the public signature of a function to accept a wider class of arguments might be considered backwards-compatible since the previous calls to the function will still work.
But if your language has type inference, now the previous calls have to actually specify the type of their arguments since the type inference algorithm can no longer resolve all the types.
So you can break SOMEONE'S build by accepting more types of arguments. It will be a one line fix, but if that fix has to be made upstream...
Also, some of the risk calculation can be pushed down onto tooling and the community. As an example, if more than the normal amounts of issues are reported against a release, the risk for the release can be automatically increased without anyone needing to be diligent in updating it and things can get automatically rolled back if the change was found to be too risky.
Semver requires a project to be more diligent than many projects are willing/able to be, and requires all changes fit nicely into the semver categories. Too many changes don't fit neatly into semver, especially when libraries are used cross platform and in different programming languages. Say a project switches from GCC to Clang, semver has no official way to express that. Release.Risk can handle it by assigning a amount of risk to the update and pretty much any other unforeseen corner case too as it doesn't try and categorize the risk. Also different projects have different risk profiles which semver completely ignores the concept of (glibc is more risk adverse than the JS library of the day). Semver also doesn't indicate any difference between a new feature that is self contained or one that touches a core piece of code, the former is much less risky than the later.
If there's a risk that a package's functionality could break between releases it can be signaled through other channels. For example, you can keep unstable code in an "experimental" module, or hide unstable functionality behind a compiler flag. The binary compatibility (ABI) of a compiled package can be signaled with a SOVERSION or with symbol versioning.
I guess I would hope that the packages I use that do publish a public API don't go changing the guts of the package in possibly unstable ways, at least not without lots of testing and maybe a few alpha/beta releases to let the experimental changes stabilize with early adopters. If I was using a library where core functionality was breaking every few releases for unclear reasons, I would argue that it's probably better to just find a more stable library to use than to put the effort into quantifying instability somehow.
You use SemVer when you are distributing a software package supporting a public API to third parties. If you are just running a service thst you develop.In house supporting a public API, you don't need SemVer. Arguably, SemVer is less useful if the software supports multiple public APIs for which independent, versions specs are available, though it is still meaningful and may be worthwhile in that case; though simple sequential versioning with a statement on API version compliance of each product version is probably more valuable.
Ultimately, it's a matter of choosing the right tool for the job, and SemVer is well-suited to the job it is intended for.
This will definitely work fine for software that's delivered to the users. I don't really care about Chrome's or Gmail's version, especially since the update process is transparent to me. The APIs should be versioned on their own and everything is fine.
On the other hand, I really appreciate when semver is used by libraries (jars, gems etc.). From developer's perspective it really helps with updating these dependencies in your own code - a quick look tells you whether it's just a simple bugfix/patch that probably doesn't affect you or something more serious that you should be careful with when bumping dependency version. Because of that, I wouldn't call it an anti-pattern. I'd say it's rather one of possible approaches that will work fine in some cases and not so well in other.
For end user software, i.e big $$$ enterprise software, there's no point in using it. Unless the app itself is a platform for other apps (in which case you're really an API/library anyway), it's beyond overkill. Heck it's downright confusing to most business users. Arguably any sizable UI change would be a "major version" because you moved a button across the screen. For that type of software I go for <major>.<minor> which are chosen to coincide with marketing campaigns.
Sometimes a "software package" encompasses multiple concurrent "API versions", which means that depending on whether you care about the API in question, the package may or may not be changing something you care about. When it's unified to a single package-wide version then you have no idea. As Rich Hickey put it in his talk on the subject[0], all you know is that "something changed."
[0] https://news.ycombinator.com/item?id=13085952 (video link + comment thread)
GitVersion looks at your git history and works out
the semantic version of the commit being built.
These days though the mantra seems to be "push to prod", and thus you may as well increment the major number on every push...
Your software should define what the inputs are and what the outputs are. It should be clear when you're breaking an interface.
Using CD as a reason to find alternatives to Semver is misguided - they are completely unrelated.
For a public API, Semver is useful, that's it.
If it's not exposing any kind of API, Semver has little meaning.
6.3.0 Bump version number to 6.3.0.
6.3.1 The "Remake the Makefile" Version
6.3.2 Bug fix---use $(RM) instead of /bin/rm
6.3.3 Bug fix---the "all" target does not depend upon "depend".
6.3.4 Bug fix---add restrict to some parameters.
6.3.5 Bug fix---fix compiler warnings from CLang.
6.3.6 Bug fix---guard against some possibly undefined defines.
6.3.7 Bug fix---update dependencies in Makefile
6.4.0 The "Trees For The Nodes" Version
6.5.0 The "PairListCreate()" Version
6.6.0 The "Go for Gopher URLs" Version
6.6.1 Bug fix---use c99 instead of gcc
6.6.2 Bug fix---use $(DESTDIR) when installing
6.6.3 Bug fix---replace malloc()/memset() pair with calloc()
6.7.0 The "Christmas Cleanup" Version
6.8.0 The "Breaking Up Is Hard To Do" Version
6.8.1 Bug fix---potential buffer overwrite.
6.8.2 Bug fix---add missing headerfile.
For the application, I've found semver not to be much of a win. The versions:
v4.6.0 The 'XXXX FaceGoogleMyTwitterPlusSpaceBook' Version
v4.6.1 Bug fix---double free
v4.6.2 Bug fix---if not using email notification, code doesn't compile
v4.6.3 Bug fix---don't use _IO_cookie_io_functions_t
v4.6.4 Bug fix---potential double free (yet again).
v4.6.5 Bug fix---encoded entries via email mess things up.
v4.6.6 Bug fix---unauthorized person posting via email leads to double fclose()
v4.6.7 Bug fix---a NULL tumbler crashes the program.
v4.7.0 The 'Tumblers Reloaded' Version
v4.7.1 Bug fix---date checking on exiting tumbler_new() was borked.
v4.7.2 Bug fix---previous and last calculations were borked.
v4.7.3 Bug fix---check tumbler date(s) against last entry, not the current time
v4.7.4 Bug fix---current link was wrong
v4.7.5 Bug fix---the assert() when comparing dates was wrong
v4.8.0 The 'Constant Upgrade' Version
v4.9.0 The 'Unused API Paramters' Version
v4.9.1 Bug fix---getline() called with incorrect parameters.
v4.9.2 Bug fix---dependencies got out of whack.
v4.9.3 Bug fix---used the wrong name when generating the tarball.
v4.9.4 Bug fix---removed compiler warnings under different compiler options.
v4.9.5 Bug fix---assert() was too assertive.
v4.9.6 Bug fix---I was a bit too assertive in the callback code.
v4.9.7 Bug fix---fix header guards.
v4.10.0 The 'Spiffier Email' Version
v4.11.0 The 'Go For Gopher' Version
v4.11.1 Bug fix---potential memory leaks fixed
v4.11.2 Bug fix---notify_emaillist() was borked
v4.11.3 Bug fix---memory corruption
v4.12.0 The "Somewhat Arbitrary Christmas Release" Version
v4.13.0 The "Target Advertisers" Version