5 ms·

Most of what you touch on is covered by semantic versioning. (https://semver.org https://semver.org), and IMO should be mandatory reading by anyone in software

Most of what you touch on is covered by semantic versioning. (https://semver.org https://semver.org), and IMO should be mandatory reading by anyone in software development. It sort of looks like you are sort of aware of it, but maybe not entirely. What you called a minor version is typically called a "patch" version. So it goes. MAJOR.MINOR.PATCH Major version bump can change anything. Minor versions are generally safe to upgrade, but will change the api in a backwards compatible way. Patch version updates make no change to the api. One of the worst things to deal with is libraries for which maintainers have broken the semver contract.

ahartmetz 5y ago
Qt is exemplary in that. There are ironclad rules that only MINOR adds new features and only MAJOR breaks API. And PATCH is strictly for bugfixes. Binary compatibility is guaranteed as well so that an application compiled against 5.0.0 will dynamically link against 5.15.2 and run fine unless it relied on clear bugs. There are exceptions for things like input method plugins, for which one needs to explicitly opt in to using internal API with build sysem flags. Without the opt-in, the corresponding private headers are not accessible.
maweki 5y ago
You have to define the notion of "backwards compatible" though, as this is the core of semver. To be strict, a bugfix is not backwards compatible. You explicitly change the behaviour of a function or interface. There's an interesting paper on checked semantic versioning [1] and you will get a new MAJOR version if you don't explicitly add the NOCOMPARE-pragma to a bugfix, as the prover (obviously) can not show the original function and the bugfixed function to be equal (usually they are not for some input). Backwards compatibility is hugely in the eye of the beholder (Hyrum's Law). So this is not a cut-and-dry issue. [1] https://drops.dagstuhl.de/opus/volltexte/2018/8456/ https://drops.dagstuhl.de/opus/volltexte/2018/8456/
- okamiueru 5y ago
  I think the underlying assumption here is that this is versioning for humans (and package managers). It isn't 100% ironclad and fool proof. It really only tries to make the job better/easier for those who rely on other libraries by baking in an educated answer to the following question: > If I upgrade the library from X.Y.Z to A.B.C, what can I expect to have changed, and to what extent do I need to do anything after I make the upgrade to make my code work the same? I don't find it interesting that, technically, any observed change to the library can potentially break code. If I use reflection to branch on number of methods available, a bump in minor version can introduce a method to the API, and thus break my code. Making an observation of this is one thing, naming it after one self is a tad on the egotistical side. Other than that, I agree completely that the difficult part is defining what "backwards compatible" really means. However, to be clear, changing behavior is not the same as being backwards incompatible. I expect bugfixes to make my code function more correct and more reliably. I can reasonably expect minor versions to add functions or features that don't get in the way, and I can expect nothing from major version upgrades, so those will always need to be done with some extra care.
humanrebar 5y ago
The biggest problem I have with semver is that we don't have good enough tooling to reject minor or patch version bumps when major version bumps are actually warranted. I'm not sure it's possible to have that thorough of analysis in general. Semver is handy for understanding what the maintainer meant to do. I guess in a lot of circumstances that's not nothing.
- account42 5y ago
  > The biggest problem I have with semver is that we don't have good enough tooling to reject minor or patch version bumps when major version bumps are actually warranted. I'm not sure it's possible to have that thorough of analysis in general. The biggest problem with automated tooling is that there is a nontrivial subjective component to this. If you look at things strictly, any bug fix that changes externally observable behavior can be a breaking change - but bumping the major version for every release defeats the purpose of SemVer.
  - okamiueru 5y ago
    If the change actually breaks existing use, then bumping the major version of every such release is *exactly* the purpose of SemVer. One important note that is often overlooked, as it isn't part of the short SemVer summary, is that major version 0 is special. The rules for minor and patch versions do not apply, and anything can change at any time. In other words, a project and library can explore its API freely and make as many wild changes as it pleases. Once it matures, it can be made 1.0.0, and the whole point of doing so is to communicate that the rules of major, minor and patch version bumps can be expected to be followed.
account42 5y ago
I think GPs main point is not covered by semver at all - namely to not break anything out of the blue but have a transition period where API consumers can upgrade at their own leisure.
- okamiueru 5y ago
  I do not know what GP is short for, apologies if I'm missing your point in my reply. One, if not the most important part of semver is communicating the nature of the changes, and in particular, how that change affects the use. I once used a library/tool that would detect vulnerabilities. The maintainers thought it would be a good idea to turn it in to a paid service, and a minor version upgrade caused it to fail silently due to lack of a token. When I noticed it by coincidence, I raised the issue of it not being communicated properly, and they said they had made every effort at raising awareness about the change through blog posts, twitter, etc. However, few people really subscribe or follow this kind of feeds. The change that came as an increment in minor version had IMO broken semantic versioning. If it instead had been followed, it would have communicated exactly that some care when upgrading was necessary, and allowed the API consumers to upgrade at their own leisure.
  - account42 5y ago
    > One, if not the most important part of semver is communicating the nature of the changes, and in particular, how that change affects the use. Yes, SemVer communicates breaking changes, but only after they have happened. The point is that you should have a migration path ready long before the old API is no longer available.
    - okamiueru 5y ago
      What do you mean by "after they have happened"? The changes to an updated library don't affect you until you have upgraded to that version. The whole point of semantic versioning is to allow you or package managers you use to limit which libraries to update. So, semver is to let you know of braking changes exactly before they would happen, because until you actually upgrade the library, the change hasn't happened. Surely this makes sense? Maybe we are talking past each other.
cecilpl2 5y ago
https://medium.com/@xzyfer/why-node-sass-broke-your-code-and-semver-1b3e409c57b9 https://medium.com/@xzyfer/why-node-sass-broke-your-code-and... What do you think of this example, where a library made a breaking, non-backwards compatible change, causing user code to throw fatal errors. They defended their point that this is only a minor version increment since the working user code was actually erroneously working and should have been throwing fatal errors the whole time.
- WhyNotHugo 5y ago
  If it broke the exposed API, it should not be a minor. It doesn't matter if it's "by design" or not, people still rely on it and semver is how you communicate the breakage to them.
  - beckingz 5y ago
    What if it counts as a bug fix?
    - dagw 5y ago
      It really depends on the bug? If it is a bug that causes your program to crash or return obviously invalid output then it's probably OK to fix it. But if the 'bug' does something useful that just happens to be undocumented or contradicts the documentation, then you need to be a lot more careful about 'fixing' it. Especially if it's clear that lots of people are relying on that bug as a feature.
    - squeaky-clean 5y ago
      I ran into this recently, I'm sure many others did too (I'm not the issue poster). https://github.com/eventlet/eventlet/issues/702 https://github.com/eventlet/eventlet/issues/702 https://github.com/benoitc/gunicorn/pull/2581 https://github.com/benoitc/gunicorn/pull/2581 While the bug does seem pretty critical for websocket users, the patch-version-change ended up breaking any application that uses gunicorn with eventlet (even if you don't use websockets). It feels slightly like my fault, because eventlet has been at v0.x.x for 9 years now. I used to be a bit hesitant about using anything that couldn't declare a version 1.0.0. I guess I've learned my lesson and just won't use any v0 library except in hobby projects now.
TheCoelacanth 5y ago
Only "Announce breaking changes." is covered by semver. A library that makes a breaking change every week could be following semver if it bumps the major version every time, but they are not taking backwards compatibility seriously.

ahartmetz 5y ago

Qt is exemplary in that. There are ironclad rules that only MINOR adds new features and only MAJOR breaks API. And PATCH is strictly for bugfixes. Binary compatibility is guaranteed as well so that an application compiled against 5.0.0 will dynamically link against 5.15.2 and run fine unless it relied on clear bugs. There are exceptions for things like input method plugins, for which one needs to explicitly opt in to using internal API with build sysem flags. Without the opt-in, the corresponding private headers are not accessible.

maweki 5y ago

You have to define the notion of "backwards compatible" though, as this is the core of semver. To be strict, a bugfix is not backwards compatible. You explicitly change the behaviour of a function or interface. There's an interesting paper on checked semantic versioning [1] and you will get a new MAJOR version if you don't explicitly add the NOCOMPARE-pragma to a bugfix, as the prover (obviously) can not show the original function and the bugfixed function to be equal (usually they are not for some input). Backwards compatibility is hugely in the eye of the beholder (Hyrum's Law). So this is not a cut-and-dry issue. [1] https://drops.dagstuhl.de/opus/volltexte/2018/8456/ https://drops.dagstuhl.de/opus/volltexte/2018/8456/

okamiueru 5y ago
I think the underlying assumption here is that this is versioning for humans (and package managers). It isn't 100% ironclad and fool proof. It really only tries to make the job better/easier for those who rely on other libraries by baking in an educated answer to the following question: > If I upgrade the library from X.Y.Z to A.B.C, what can I expect to have changed, and to what extent do I need to do anything after I make the upgrade to make my code work the same? I don't find it interesting that, technically, any observed change to the library can potentially break code. If I use reflection to branch on number of methods available, a bump in minor version can introduce a method to the API, and thus break my code. Making an observation of this is one thing, naming it after one self is a tad on the egotistical side. Other than that, I agree completely that the difficult part is defining what "backwards compatible" really means. However, to be clear, changing behavior is not the same as being backwards incompatible. I expect bugfixes to make my code function more correct and more reliably. I can reasonably expect minor versions to add functions or features that don't get in the way, and I can expect nothing from major version upgrades, so those will always need to be done with some extra care.

humanrebar 5y ago

The biggest problem I have with semver is that we don't have good enough tooling to reject minor or patch version bumps when major version bumps are actually warranted. I'm not sure it's possible to have that thorough of analysis in general. Semver is handy for understanding what the maintainer meant to do. I guess in a lot of circumstances that's not nothing.

account42 5y ago
> The biggest problem I have with semver is that we don't have good enough tooling to reject minor or patch version bumps when major version bumps are actually warranted. I'm not sure it's possible to have that thorough of analysis in general. The biggest problem with automated tooling is that there is a nontrivial subjective component to this. If you look at things strictly, any bug fix that changes externally observable behavior can be a breaking change - but bumping the major version for every release defeats the purpose of SemVer.
- okamiueru 5y ago
  If the change actually breaks existing use, then bumping the major version of every such release is *exactly* the purpose of SemVer. One important note that is often overlooked, as it isn't part of the short SemVer summary, is that major version 0 is special. The rules for minor and patch versions do not apply, and anything can change at any time. In other words, a project and library can explore its API freely and make as many wild changes as it pleases. Once it matures, it can be made 1.0.0, and the whole point of doing so is to communicate that the rules of major, minor and patch version bumps can be expected to be followed.

account42 5y ago

I think GPs main point is not covered by semver at all - namely to not break anything out of the blue but have a transition period where API consumers can upgrade at their own leisure.

okamiueru 5y ago
I do not know what GP is short for, apologies if I'm missing your point in my reply. One, if not the most important part of semver is communicating the nature of the changes, and in particular, how that change affects the use. I once used a library/tool that would detect vulnerabilities. The maintainers thought it would be a good idea to turn it in to a paid service, and a minor version upgrade caused it to fail silently due to lack of a token. When I noticed it by coincidence, I raised the issue of it not being communicated properly, and they said they had made every effort at raising awareness about the change through blog posts, twitter, etc. However, few people really subscribe or follow this kind of feeds. The change that came as an increment in minor version had IMO broken semantic versioning. If it instead had been followed, it would have communicated exactly that some care when upgrading was necessary, and allowed the API consumers to upgrade at their own leisure.
- account42 5y ago
  > One, if not the most important part of semver is communicating the nature of the changes, and in particular, how that change affects the use. Yes, SemVer communicates breaking changes, but only after they have happened. The point is that you should have a migration path ready long before the old API is no longer available.
  - okamiueru 5y ago
    What do you mean by "after they have happened"? The changes to an updated library don't affect you until you have upgraded to that version. The whole point of semantic versioning is to allow you or package managers you use to limit which libraries to update. So, semver is to let you know of braking changes exactly before they would happen, because until you actually upgrade the library, the change hasn't happened. Surely this makes sense? Maybe we are talking past each other.

cecilpl2 5y ago

https://medium.com/@xzyfer/why-node-sass-broke-your-code-and-semver-1b3e409c57b9 https://medium.com/@xzyfer/why-node-sass-broke-your-code-and... What do you think of this example, where a library made a breaking, non-backwards compatible change, causing user code to throw fatal errors. They defended their point that this is only a minor version increment since the working user code was actually erroneously working and should have been throwing fatal errors the whole time.

WhyNotHugo 5y ago
If it broke the exposed API, it should not be a minor. It doesn't matter if it's "by design" or not, people still rely on it and semver is how you communicate the breakage to them.
- beckingz 5y ago
  What if it counts as a bug fix?
  - dagw 5y ago
    It really depends on the bug? If it is a bug that causes your program to crash or return obviously invalid output then it's probably OK to fix it. But if the 'bug' does something useful that just happens to be undocumented or contradicts the documentation, then you need to be a lot more careful about 'fixing' it. Especially if it's clear that lots of people are relying on that bug as a feature.
  - squeaky-clean 5y ago
    I ran into this recently, I'm sure many others did too (I'm not the issue poster). https://github.com/eventlet/eventlet/issues/702 https://github.com/eventlet/eventlet/issues/702 https://github.com/benoitc/gunicorn/pull/2581 https://github.com/benoitc/gunicorn/pull/2581 While the bug does seem pretty critical for websocket users, the patch-version-change ended up breaking any application that uses gunicorn with eventlet (even if you don't use websockets). It feels slightly like my fault, because eventlet has been at v0.x.x for 9 years now. I used to be a bit hesitant about using anything that couldn't declare a version 1.0.0. I guess I've learned my lesson and just won't use any v0 library except in hobby projects now.

TheCoelacanth 5y ago

Only "Announce breaking changes." is covered by semver. A library that makes a breaking change every week could be following semver if it bumps the major version every time, but they are not taking backwards compatibility seriously.