3 ms·

> when you're simply introducing breaking changes (but doesn't qualify as a "significant" release). I can't picture this. Breaking changes are always signific

by bronson 10y ago

> when you're simply introducing breaking changes (but doesn't qualify as a "significant" release). I can't picture this. Breaking changes are always significant, aren't they? Got an example?

eridius 10y ago
If I'm writing a library, and I want to make a relatively minor breaking change to one function (e.g. changing the type of a parameter), that's not a significant change to the whole library, but it is a breaking change and semver demands that I bump the major version number.
- prodigal_erik 10y ago
  Library users expect breaking changes to be rare and have a damn good reason. What you're describing is deprecation without any warning period ("this stuff will go away in the next major release").
- vilya 10y ago
  My opinion, as someone whose code got broken by a library micro version update just yesterday, is that the responsible thing to do is add a new function with the new args instead of changing the old one. Change the implementation of the old one so it calls through to the new one with suitable parameter values & and mark the old version as deprecated, but please don't remove it until the next major release!
  - eridius 10y ago
    That's what I do in most cases. But sometimes there's just no option. The particular case that I was referring to when I said I decided to put off changes because I didn't want to bump the version number was actually a stylistic change, renaming a method from `parse(with:)` to `parse(using:)`, in order to better match the Swift 3 naming conventions. Normally I would have just marked the old method as deprecated, except a compiler bug means that if I do so, any code using trailing-closure syntax fails to compile (https://bugs.swift.org/browse/SR-3227 https://bugs.swift.org/browse/SR-3227). So it's literally impossible for me to rename this method in this manner without deleting the old method entirely (which is a breaking change). But I just bumped the major version number recently when Swift 3 was released, and I didn't want to bump it again shortly afterwards just because I didn't consider this method name during the Swift 2->3 migration.
    - vilya 10y ago
      Fair enough, I understand the desire not to bump the major version in this case. It does still kind of suck for users of the library though. The case I was talking about was the OpenVR library, which changed the names for some of its enum values in the upgrade from 1.0.4 to 1.0.5. The change was documented in the release notes and it was straightforward to fix our code, but now we have to document that we require at least v1.0.5 and everyone building our code has to update their copy of OpenVR and so on. There are knock-on effects, is what I'm trying to say.
pfranz 10y ago
Not exactly what you're asking, but here's a wrench I've seen in semver at work. Let's say I do a overhaul to a library; either I rewrite the logic or write a new interface. I also write "shim code" that's "supposed" to be backwards compatible. It's a huge change, and the company isn't really big enough to have formal q&a or significant testing. Personally, I tend to write a lot of shim-code, but try and be aggressive about deprecating it--it's more work, but is more politically viable than getting everyone to update their code /and/ troubleshoot/trust a big change. The consensus we had was a major version bump when that's introduced and another when the shim code gets deprecated--but nobody really wants that in practice. (I never did come up with a good answer) Also, we decided that "stealing" major version numbers for speculative code was a bad idea. We'd have a lot of false starts that get abandoned and it got really confusing when the next major version got released (you're either re-using that version number or skipping a bunch). Personally, I like semver, but think versioning mechanisms can differ (going from major OSes to small libraries I write at work) based on the needs. One thing I've noticed when working on artwork for clients, they get scared and confused by large revision numbers, so we tend to keep them fairly low by keeping internal version control numbers separate from review versions.

by bronson 10y ago

> when you're simply introducing breaking changes (but doesn't qualify as a "significant" release). I can't picture this. Breaking changes are always significant, aren't they? Got an example?

eridius 10y ago

If I'm writing a library, and I want to make a relatively minor breaking change to one function (e.g. changing the type of a parameter), that's not a significant change to the whole library, but it is a breaking change and semver demands that I bump the major version number.

prodigal_erik 10y ago
Library users expect breaking changes to be rare and have a damn good reason. What you're describing is deprecation without any warning period ("this stuff will go away in the next major release").
vilya 10y ago
My opinion, as someone whose code got broken by a library micro version update just yesterday, is that the responsible thing to do is add a new function with the new args instead of changing the old one. Change the implementation of the old one so it calls through to the new one with suitable parameter values & and mark the old version as deprecated, but please don't remove it until the next major release!
- eridius 10y ago
  That's what I do in most cases. But sometimes there's just no option. The particular case that I was referring to when I said I decided to put off changes because I didn't want to bump the version number was actually a stylistic change, renaming a method from `parse(with:)` to `parse(using:)`, in order to better match the Swift 3 naming conventions. Normally I would have just marked the old method as deprecated, except a compiler bug means that if I do so, any code using trailing-closure syntax fails to compile (https://bugs.swift.org/browse/SR-3227 https://bugs.swift.org/browse/SR-3227). So it's literally impossible for me to rename this method in this manner without deleting the old method entirely (which is a breaking change). But I just bumped the major version number recently when Swift 3 was released, and I didn't want to bump it again shortly afterwards just because I didn't consider this method name during the Swift 2->3 migration.
  - vilya 10y ago
    Fair enough, I understand the desire not to bump the major version in this case. It does still kind of suck for users of the library though. The case I was talking about was the OpenVR library, which changed the names for some of its enum values in the upgrade from 1.0.4 to 1.0.5. The change was documented in the release notes and it was straightforward to fix our code, but now we have to document that we require at least v1.0.5 and everyone building our code has to update their copy of OpenVR and so on. There are knock-on effects, is what I'm trying to say.

pfranz 10y ago

Not exactly what you're asking, but here's a wrench I've seen in semver at work. Let's say I do a overhaul to a library; either I rewrite the logic or write a new interface. I also write "shim code" that's "supposed" to be backwards compatible. It's a huge change, and the company isn't really big enough to have formal q&a or significant testing. Personally, I tend to write a lot of shim-code, but try and be aggressive about deprecating it--it's more work, but is more politically viable than getting everyone to update their code /and/ troubleshoot/trust a big change. The consensus we had was a major version bump when that's introduced and another when the shim code gets deprecated--but nobody really wants that in practice. (I never did come up with a good answer) Also, we decided that "stealing" major version numbers for speculative code was a bad idea. We'd have a lot of false starts that get abandoned and it got really confusing when the next major version got released (you're either re-using that version number or skipping a bunch). Personally, I like semver, but think versioning mechanisms can differ (going from major OSes to small libraries I write at work) based on the needs. One thing I've noticed when working on artwork for clients, they get scared and confused by large revision numbers, so we tend to keep them fairly low by keeping internal version control numbers separate from review versions.