6 ms·

Strong disagree with this post. Semantic versioning means: MAJOR version when you make incompatible API changes, MINOR version when you add functionality in a b

by jph 4y ago

Strong disagree with this post. Semantic versioning means: MAJOR version when you make incompatible API changes, MINOR version when you add functionality in a backwards compatible manner, and PATCH version when you make backwards compatible bug fixes. The purpose is to enable APIs and build tools to work well, such as package manager project files that specify a version. To answer the author's questions: "When was the last time you could tell someone the difference between version 1.2.1 and 1.2.3 quickly?" I can tell it's a patch upgrade, so my team's projects can do this upgrade automatically, with tests of course. Also, I can look at the source git repo, or changelog, or equivalent. "Can you tell me when version 1.2.1 was released?" Yes, by looking at the source git repo, or git tags, or changelog, or equivalent. "What is your company/team's meaning behind a major, minor, and patch increment?" Semver specifies how to do this in the first paragraph of www.semver.org. "Who decides when a new major version is released?" The person who is responsible for the API breaking change; depending on the team and goals, this person could be the developer, or project manager, or release manager, etc. "What happens to the version where the manager or developer forgot to put together a change log?" We test for it in our git pre-commit hook and in our continuous integration. If your team isn't using those, or equivalents, then simply add a changelog and push a patch version.

ricardobeat 4y ago
The author seems to be focusing on applications. If you’re releasing an app, service or anything else that doesn’t expose a public API, there is no point in having those compatibility semantics.
- jph 4y ago
  If you're releasing an app that our teams are using, then yes please use semver, because we manage apps via system package managers (e.g. macOS brew, Windows wpm, Ubuntu apt, etc.) and containers (e.g. Docker, Podman, etc.), and infrastructure as code (e.g. Ansible, Packer, etc.). This enables our systems to automate our application updates. We do PATCH updates continuously (e.g each night), MINOR updates during system downtime (e.g. each weekend), and MAJOR updates with manual scheduling when we can look at the changelogs. If you're not managing your systems' applications with package managers or containers or infrastructure as code, then IMHO these are well worth a look.
  - wereHamster 4y ago
    Is it a breaking change if a button is moved by a few pixels in a graphical application?
    - lostcolony 4y ago
      No, because the functionality is the same. Just because a test may be so brittle that it breaks the test does not change the meaning (it just may mean you have to manually inspect the now failing test). The point is that most patch upgrades can just be run through a test suite and accepted. That may still lead to breakages, something that seemed minor and non-breaking to the developer could instead be breaking for a given user, but the point of semver is to convey actionable meaning and intent, which it does.
    - orphea 4y ago
      Yes. Also several weeks of beta are required before releasing the change, and a few blog posts about how a talented team at $COMPANY deals with challenges of UI design.
    - jph 4y ago
      If the application documentation promises a stable screenshot, but an update moves a button, then yes this is a breaking change. This comes up in the real world sometimes such as with automatic testing scripts that use absolute cursor positioning, as well as in some kinds of compliance where any graphic change requires a compliance verification of the new UI.
    - runaway 4y ago
      The first two responses to you were a solid yes and a solid no. I think that just demonstrates how the concept does not apply to application versioning.
      - lostcolony 4y ago
        One of the "Yes" responses is clearly sarcastic; the other gives an "only if you promise an unchanging UI".
- onei 4y ago
  Even if you do have an API, sometimes you have versioning built into that API anyway, e.g. in openapi and gRPC (depending on how you structure your protobuf files). At that point, a date-based version starts looking more reasonable.
- tailspin2019 4y ago
  Agreed. And even more so if you're developing a SaaS product or otherwise hosted app which is continuously updated. The closer you get to continuous delivery, the more date-based versioning can make a bit more sense as opposed to "traditional" semantic versioning (though it's still often a subjective decision).
hotpotamus 4y ago
It sounds like you want to move slow and not break things. How quaint.
- tremon 4y ago
  No, they still want to move quick, and you can do that by relying on the change signaling of your vendor: if you know the vendor is trustworthy, you can deploy minor updates with only minimal testing. If the vendor is unreliable or doesn't signal their changes accurately, every "minor" update becomes a liability, and that's where it gets slow. Companies that want to move quickly should not use unreliable vendors.
- engineerDave 4y ago
  It is possible to move fast and NOT break things. Breaking things is bad. Despite what Mark says. When you break things companies lose customers, they lose money, they lose market share, and people get fired or die.
chrisseaton 4y ago
> backwards compatible bug fixes What even is a 'backwards compatible bug fix'? Unless it's performance, isn't a bug-fix by definition not going to be backwards compatible?
- Sharlin 4y ago
  Any bugfix could be seen as backwards incompatible in the strict sense "somewhere, someone might actually depend on this buggy behavior", yes. That’s not a particularly good definition of backwards incompatibility when it comes to bugfixes, however. A more reasonable definition is "requires changes to downstream code" as in the bug cannot be fixed without changing public API as well. That said, sometimes there definitely exist bugs that a lot of users factually rely on, and changing such behaviors should not be done in patch releases.
- lostcolony 4y ago
  Which is why you provide patch notes, and why the more conservative consumers won't even auto-accept patch updates. The point is that a bug fix that doesn't change the API, and which only changes behavior to match intent and documentation, is something that requires minimal testing by the user. I.e., "fixed possible race condition where..." is a patch. It may be that a consumer relied on a particular bug when developing, yes, and that fixing it now 'breaks' their application, but that's a definite minority, and why you communicate out the fixes (and for auto-adopting patch releases, you ideally still have automatic tests to validate).
- jjav 4y ago
  > What even is a 'backwards compatible bug fix'? Unless it's performance, isn't a bug-fix by definition not going to be backwards compatible? It's a fix that makes the code work as documented, which it didn't do before, ergo had a bug. To pick a random example, the man page for strlen on Linux reads: "The strlen() function calculates the length of the string s, excluding the terminating null byte ('\0')." If it behaves differently (let's say it counts the terminating null) then strlen has a bug. The fix to that can go into a patch release because it simply fixes the interface to work as documented. You could go down a rathole of saying well maybe someone depends on the broken functionality. Sure, but that's not what the documented contract was. The documented functionality is the contract the API needs to meet.
k__ 4y ago
"MINOR version when you add functionality in a backwards compatible manner" Impossible to guarantee and thus impossible to do SemVer.
- 8organicbits 4y ago
  It's OK if systems are imperfect, they are still helpful even though exceptions may occur. Intent matters. You may even see backwards incompatible changes treated as bugs fixed in subsequent releases.
- enragedcacti 4y ago
  Almost all code is aspirational in terms of matching a spec, being backwards compatible, not having bugs, etc. Its meaningless to talk about what is guaranteed with respect to practically every piece of software in existence. What is important to a developer is "what is the risk that upgrading this software will break my deployment, and what do I gain from upgrading it", which semver relays to the developer to the best of the library author's ability.
- jjav 4y ago
  Functionality can always be added in a backward compatible manner, that is indeed the purpose of a minor release. If libfoo has two public interfaces, sing() and dance(), I can add a third interface walk() and publish a binary-compatible libfoo.so which your consuming code can link to without any concern, as your code isn't calling walk() before it existed.
  - k__ 4y ago
    The moment you allow bugs, you can't ensure backwards compatible changes. That makes semver as good as any other scheme, including GitDate.
    - jjav 4y ago
      > The moment you allow bugs, you can't ensure backwards compatible changes. I'm not sure what this even means, unless you're talking of the joke of "someone depended on the bug"? A bug, by its very definition, means code that doesn't behave as the documented interface description states. Fixing bugs means correcting mistakes in the code so that now it does behave as documented. That's what patch releases do.
jjav 4y ago
Strongly agree with your strong disagreement. The blog author doesn't seem to have any experience releasing software that others need to actually rely on. This dovetails nicely with the discussion yesterday on using dependencies (https://news.ycombinator.com/item?id=31692606 https://news.ycombinator.com/item?id=31692606). I would not want to have to depend on any library this blog author releases. From that list of random meanigless dates, how would tools know which release is a compatible bugfix and which ones carries breaking changes? The assumption there seems to be that release date is the one and only thing consumers of the release care about. But as a consumer of some library, I can tell that I mostly don't care at all about the release date. But I must know what the release contains in terms of change disruption, which is the purpose of versioning.
engineerDave 4y ago
TBH the OP post seems to be highlighting that "when we forget history, we're doomed to repeat it." Not trying to be ageist but a younger dev wouldn't have context on a time when the industry had timestamps as versions and the core reason why SemVer became preferred, as you describe above.

by jph 4y ago

ricardobeat 4y ago

The author seems to be focusing on applications. If you’re releasing an app, service or anything else that doesn’t expose a public API, there is no point in having those compatibility semantics.

jph 4y ago
If you're releasing an app that our teams are using, then yes please use semver, because we manage apps via system package managers (e.g. macOS brew, Windows wpm, Ubuntu apt, etc.) and containers (e.g. Docker, Podman, etc.), and infrastructure as code (e.g. Ansible, Packer, etc.). This enables our systems to automate our application updates. We do PATCH updates continuously (e.g each night), MINOR updates during system downtime (e.g. each weekend), and MAJOR updates with manual scheduling when we can look at the changelogs. If you're not managing your systems' applications with package managers or containers or infrastructure as code, then IMHO these are well worth a look.
- wereHamster 4y ago
  Is it a breaking change if a button is moved by a few pixels in a graphical application?
  - lostcolony 4y ago
    No, because the functionality is the same. Just because a test may be so brittle that it breaks the test does not change the meaning (it just may mean you have to manually inspect the now failing test). The point is that most patch upgrades can just be run through a test suite and accepted. That may still lead to breakages, something that seemed minor and non-breaking to the developer could instead be breaking for a given user, but the point of semver is to convey actionable meaning and intent, which it does.
  - orphea 4y ago
    Yes. Also several weeks of beta are required before releasing the change, and a few blog posts about how a talented team at $COMPANY deals with challenges of UI design.
  - jph 4y ago
    If the application documentation promises a stable screenshot, but an update moves a button, then yes this is a breaking change. This comes up in the real world sometimes such as with automatic testing scripts that use absolute cursor positioning, as well as in some kinds of compliance where any graphic change requires a compliance verification of the new UI.
  - runaway 4y ago
    The first two responses to you were a solid yes and a solid no. I think that just demonstrates how the concept does not apply to application versioning.
    - lostcolony 4y ago
      One of the "Yes" responses is clearly sarcastic; the other gives an "only if you promise an unchanging UI".
onei 4y ago
Even if you do have an API, sometimes you have versioning built into that API anyway, e.g. in openapi and gRPC (depending on how you structure your protobuf files). At that point, a date-based version starts looking more reasonable.
tailspin2019 4y ago
Agreed. And even more so if you're developing a SaaS product or otherwise hosted app which is continuously updated. The closer you get to continuous delivery, the more date-based versioning can make a bit more sense as opposed to "traditional" semantic versioning (though it's still often a subjective decision).

hotpotamus 4y ago

It sounds like you want to move slow and not break things. How quaint.

tremon 4y ago
No, they still want to move quick, and you can do that by relying on the change signaling of your vendor: if you know the vendor is trustworthy, you can deploy minor updates with only minimal testing. If the vendor is unreliable or doesn't signal their changes accurately, every "minor" update becomes a liability, and that's where it gets slow. Companies that want to move quickly should not use unreliable vendors.
engineerDave 4y ago
It is possible to move fast and NOT break things. Breaking things is bad. Despite what Mark says. When you break things companies lose customers, they lose money, they lose market share, and people get fired or die.

chrisseaton 4y ago

> backwards compatible bug fixes What even is a 'backwards compatible bug fix'? Unless it's performance, isn't a bug-fix by definition not going to be backwards compatible?

Sharlin 4y ago
Any bugfix could be seen as backwards incompatible in the strict sense "somewhere, someone might actually depend on this buggy behavior", yes. That’s not a particularly good definition of backwards incompatibility when it comes to bugfixes, however. A more reasonable definition is "requires changes to downstream code" as in the bug cannot be fixed without changing public API as well. That said, sometimes there definitely exist bugs that a lot of users factually rely on, and changing such behaviors should not be done in patch releases.
lostcolony 4y ago
Which is why you provide patch notes, and why the more conservative consumers won't even auto-accept patch updates. The point is that a bug fix that doesn't change the API, and which only changes behavior to match intent and documentation, is something that requires minimal testing by the user. I.e., "fixed possible race condition where..." is a patch. It may be that a consumer relied on a particular bug when developing, yes, and that fixing it now 'breaks' their application, but that's a definite minority, and why you communicate out the fixes (and for auto-adopting patch releases, you ideally still have automatic tests to validate).
jjav 4y ago
> What even is a 'backwards compatible bug fix'? Unless it's performance, isn't a bug-fix by definition not going to be backwards compatible? It's a fix that makes the code work as documented, which it didn't do before, ergo had a bug. To pick a random example, the man page for strlen on Linux reads: "The strlen() function calculates the length of the string s, excluding the terminating null byte ('\0')." If it behaves differently (let's say it counts the terminating null) then strlen has a bug. The fix to that can go into a patch release because it simply fixes the interface to work as documented. You could go down a rathole of saying well maybe someone depends on the broken functionality. Sure, but that's not what the documented contract was. The documented functionality is the contract the API needs to meet.

k__ 4y ago

"MINOR version when you add functionality in a backwards compatible manner" Impossible to guarantee and thus impossible to do SemVer.

8organicbits 4y ago
It's OK if systems are imperfect, they are still helpful even though exceptions may occur. Intent matters. You may even see backwards incompatible changes treated as bugs fixed in subsequent releases.
enragedcacti 4y ago
Almost all code is aspirational in terms of matching a spec, being backwards compatible, not having bugs, etc. Its meaningless to talk about what is guaranteed with respect to practically every piece of software in existence. What is important to a developer is "what is the risk that upgrading this software will break my deployment, and what do I gain from upgrading it", which semver relays to the developer to the best of the library author's ability.
jjav 4y ago
Functionality can always be added in a backward compatible manner, that is indeed the purpose of a minor release. If libfoo has two public interfaces, sing() and dance(), I can add a third interface walk() and publish a binary-compatible libfoo.so which your consuming code can link to without any concern, as your code isn't calling walk() before it existed.
- k__ 4y ago
  The moment you allow bugs, you can't ensure backwards compatible changes. That makes semver as good as any other scheme, including GitDate.
  - jjav 4y ago
    > The moment you allow bugs, you can't ensure backwards compatible changes. I'm not sure what this even means, unless you're talking of the joke of "someone depended on the bug"? A bug, by its very definition, means code that doesn't behave as the documented interface description states. Fixing bugs means correcting mistakes in the code so that now it does behave as documented. That's what patch releases do.

jjav 4y ago

Strongly agree with your strong disagreement. The blog author doesn't seem to have any experience releasing software that others need to actually rely on. This dovetails nicely with the discussion yesterday on using dependencies (https://news.ycombinator.com/item?id=31692606 https://news.ycombinator.com/item?id=31692606). I would not want to have to depend on any library this blog author releases. From that list of random meanigless dates, how would tools know which release is a compatible bugfix and which ones carries breaking changes? The assumption there seems to be that release date is the one and only thing consumers of the release care about. But as a consumer of some library, I can tell that I mostly don't care at all about the release date. But I must know what the release contains in terms of change disruption, which is the purpose of versioning.

engineerDave 4y ago

TBH the OP post seems to be highlighting that "when we forget history, we're doomed to repeat it." Not trying to be ageist but a younger dev wouldn't have context on a time when the industry had timestamps as versions and the core reason why SemVer became preferred, as you describe above.