5 ms·

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

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.
joshuamorton 5y ago
Per hyrums law, this would mean that essentially all changes should result in a major version bump, which defeats the purpose.
- okamiueru 5y ago
  It also makes "Hyrum's Law" pretty useless, doesn't it? Who names something like that after themselves? Well, I know at least one such case.
  - joshuamorton 5y ago
    > It also makes "Hyrum's Law" pretty useless, doesn't it? Not really. Hyrum's law is descriptive of reality and borne out of experience trying to update/change things. The point of it is to remind you that even when you think you aren't breaking things, you probably are breaking someone's workflow, and that your API surface is much larger than you think it is (performance, threading, ordering characteristics, etc. are all things that your dependencies will routinely rely on). > Who names something like that after themselves? Well, I know at least one such case. He didn't. Titus Winters probably deserves credit for the name. Hyrum deserves credit for the observation.
    - okamiueru 5y ago
      He sure makes no small attempt at marketing the term, and himself https://www.hyrumslaw.com/ https://www.hyrumslaw.com/ In any case, my point is that it this observation has no relevance on the applicability of semantic versioning. One is a practical approach at making the best out of versioning. The other is a rather simple observation that given sufficient enough users of an API, all parts of the API will be depended on by someone. To go and suggest that the logical extreme of a though experiment that, any change (bug fix or what have you) on an API, and given wide enough usage, will change/break something for someone, should somehow conclude in a defeatist mentality of "what's the point, everything becomes a major version", is... in my honest opinion, as uninteresting of an observation as they come. I'm sure it has more interesting applications elsewhere. But then again, maybe I don't get what is supposed to be profound, or applicable, and I'm all ears.
      - joshuamorton 5y ago
        > One is a practical approach at making the best out of versioning. I think the observation is that this is sort of going to inevitably fail, and people will get mad at you anyway (perhaps more mad than if you didn't have any semver promise to begin with). Right, like say you maintain a library and refactor something in a patch version bump. It affects something that isn't a documented aspect of your api, but is nonetheless something I depend on. I complain to you that you broke me with a patch upgrade. Well who is right? You did break me. Should I continue to trust you? Should I pin to a patch version (this makes semver useless)? Should you take more care to not break observable behaviors? How can you even know which behaviors are depended on, many will be unknown unknowns! The ultimate conclusion from this approach is that for a widely enough used api, you will always break someone, so you need to ship a migration story instead of a change, or you need a way to assert that your change won't break any of your users, which short of being able to run all of your dependencies tests isn't possible. This can be achieved in a corporate world, but not in the OSS world. And so yes, one of the fundamental truths of software engineering is that semver is fundamentally broken. It may be the best thing we've got, but it's absolutely not a magic pixie dust. You will still break your dependencies, and your dependencies will still break you, and you should prepare for that, semver or not. > He sure makes no small attempt at marketing the term, and himself https://www.hyrumslaw.com/ https://www.hyrumslaw.com/ Yes, and? It seems odd to drag someone for marketing themselves, on of all places, hacker news.

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.

joshuamorton 5y ago

Per hyrums law, this would mean that essentially all changes should result in a major version bump, which defeats the purpose.

okamiueru 5y ago
It also makes "Hyrum's Law" pretty useless, doesn't it? Who names something like that after themselves? Well, I know at least one such case.
- joshuamorton 5y ago
  > It also makes "Hyrum's Law" pretty useless, doesn't it? Not really. Hyrum's law is descriptive of reality and borne out of experience trying to update/change things. The point of it is to remind you that even when you think you aren't breaking things, you probably are breaking someone's workflow, and that your API surface is much larger than you think it is (performance, threading, ordering characteristics, etc. are all things that your dependencies will routinely rely on). > Who names something like that after themselves? Well, I know at least one such case. He didn't. Titus Winters probably deserves credit for the name. Hyrum deserves credit for the observation.
  - okamiueru 5y ago
    He sure makes no small attempt at marketing the term, and himself https://www.hyrumslaw.com/ https://www.hyrumslaw.com/ In any case, my point is that it this observation has no relevance on the applicability of semantic versioning. One is a practical approach at making the best out of versioning. The other is a rather simple observation that given sufficient enough users of an API, all parts of the API will be depended on by someone. To go and suggest that the logical extreme of a though experiment that, any change (bug fix or what have you) on an API, and given wide enough usage, will change/break something for someone, should somehow conclude in a defeatist mentality of "what's the point, everything becomes a major version", is... in my honest opinion, as uninteresting of an observation as they come. I'm sure it has more interesting applications elsewhere. But then again, maybe I don't get what is supposed to be profound, or applicable, and I'm all ears.
    - joshuamorton 5y ago
      > One is a practical approach at making the best out of versioning. I think the observation is that this is sort of going to inevitably fail, and people will get mad at you anyway (perhaps more mad than if you didn't have any semver promise to begin with). Right, like say you maintain a library and refactor something in a patch version bump. It affects something that isn't a documented aspect of your api, but is nonetheless something I depend on. I complain to you that you broke me with a patch upgrade. Well who is right? You did break me. Should I continue to trust you? Should I pin to a patch version (this makes semver useless)? Should you take more care to not break observable behaviors? How can you even know which behaviors are depended on, many will be unknown unknowns! The ultimate conclusion from this approach is that for a widely enough used api, you will always break someone, so you need to ship a migration story instead of a change, or you need a way to assert that your change won't break any of your users, which short of being able to run all of your dependencies tests isn't possible. This can be achieved in a corporate world, but not in the OSS world. And so yes, one of the fundamental truths of software engineering is that semver is fundamentally broken. It may be the best thing we've got, but it's absolutely not a magic pixie dust. You will still break your dependencies, and your dependencies will still break you, and you should prepare for that, semver or not. > He sure makes no small attempt at marketing the term, and himself https://www.hyrumslaw.com/ https://www.hyrumslaw.com/ Yes, and? It seems odd to drag someone for marketing themselves, on of all places, hacker news.