search

mahmoud / calver

📅 The web's go-to resource for Calendar Versioning info.
https://calver.org
Other
490 stars 32 forks source link

What about breaking changes? #4

Open bryant1410 opened 6 years ago

bryant1410 commented 6 years ago

I think this versioning scheme should contemplate breaking changes.

A very important feature I see in today's common approaches such as semver is that they reflect the breaking changes in their numbering scheme. However, I see there is nothing similar stated in this specification. Shouldn't it be contemplated?

I would be concerned if I have several dependencies using this scheme and I want to update them. Will certain updates break my code? I will have to check and remember each documentation to find which ones break compatibility (for instance, twisted states that the first two numbers indicate the API compatibility).

mahmoud commented 6 years ago

Hey Santiago! You bring up a very understandable concern. It's slightly discussed on calver.org, in so far as Twisted and Ubuntu LTS provide a time-based SLA on supported APIs. I think this is by far the most useful and pragmatic approach.

You might also like this frank discussion of SemVer's ideals and its inability to fulfill them: https://sedimental.org/designing_a_version.html#semantic-versioning

The essay above was written a few years ago and didn't have the benefit of the veil being pulled back on a very important example: npm. The JavaScript "community" leverages SemVer to an extreme degree. The result? Tiny libraries with tiny APIs. But this should be OK, right? Fine-grained libraries with automatic fine-grained version control, right?

In practice, we see that breakage is even more extensive and codebases are even more fragile than traditional models. There is no natural or objective definition of a "public API", and even if there's some pluralistic consensus, people make mistakes when dealing with such nuances.

Instead, CalVer succeeds through simplicity and communication. It encourages building developer-to-developer understandings around what constitutes manageable velocity, through documentation and other channels. And frankly, I've found developers prefer that sort of arrangement :)

bryant1410 commented 6 years ago

Hey Santiago! You bring up a very understandable concern. It's slightly discussed on calver.org, in so far as Twisted and Ubuntu LTS provide a time-based SLA on supported APIs. I think this is by far the most useful and pragmatic approach.

You might also like this frank discussion of SemVer's ideals and its inability to fulfill them: https://sedimental.org/designing_a_version.html#semantic-versioning

That's a very interesting discussion.

The essay above was written a few years ago and didn't have the benefit of the veil being pulled back on a very important example: npm. The JavaScript "community" leverages SemVer to an extreme degree. The result? Tiny libraries with tiny APIs. But this should be OK, right? Fine-grained libraries with automatic fine-grained version control, right?

In practice, we see that breakage is even more extensive and codebases are even more fragile than traditional models. There is no natural or objective definition of a "public API", and even if there's some pluralistic consensus, people make mistakes when dealing with such nuances.

I'm not that familiarized with javascript development, but there are contexts in which this is not a common problem. For example, in Android development I haven't commonly seen libraries increasing the patch version number but at the same time introducing a breaking change.

Instead, CalVer succeeds through simplicity and communication. It encourages building developer-to-developer understandings around what constitutes manageable velocity, through documentation and other channels. And frankly, I've found developers prefer that sort of arrangement :)

I agree there's some kind of punishment by SemVer when you don't increase your major version number, and it can be seen as outdated by some people, and this is greatly solved by CalVer. However, I find quite useful to have the intended API-break to be reflected in the version number of a project dependencies, when deciding to update several of them or not. At least is what the developer states. Even when some of them abuse the 0.x scheme. Couldn't we have both things? Can CalVer reflect that as well?

mahmoud commented 6 years ago

It's not at all just JavaScript, I can't even begin to enumerate the times I've seen this happen.

Depending on the scale of the API break, the right thing to do is rename the project. From Zope3/BlueBream to characteristic/attrs, this strategy has worked out best for new users and old. It may not be good for building the #brand, but it's best for the ecosystem.

If someone wants to use a character or two after the version number to indicate that a major breaking change occurred, it can still be CalVer, but I would find it a stretch to make that a recommendation. Besides, CalVer is a mostly descriptive "specification", so there would have to be some actual examples to merit putting the practice on the site.

bryant1410 commented 6 years ago

It's not at all just JavaScript, I can't even begin to enumerate the times I've seen this happen.

Depending on the scale of the API break, the right thing to do is rename the project. From Zope3/BlueBream to characteristic/attrs, this strategy has worked out best for new users and old. It may not be good for building the #brand, but it's best for the ecosystem.

Yeah, in Java too: Java Interoperability Policy for Major Version Updates

If someone wants to use a character or two after the version number to indicate that a major breaking change occurred, it can still be CalVer, but I would find it a stretch to make that a recommendation. Besides, CalVer is a mostly descriptive "specification", so there would have to be some actual examples to merit putting the practice on the site.

mahmoud commented 6 years ago

Just to expand on that last comment a little more: I've seen this happen in JavaScript and Python, but I think frequency is correlated with the high-level-ness of the interface. That is, I've seen this happen most in interfaces, both APIs and UIs.

Because there's no consensus with what constitutes a breaking change in an API (e.g., is adding a field a breaking change? is changing the error message on error responses a breaking change?), the only way to get some form of breaking change semantics would be to have extensive documentation. This defeats the purpose of SemVer (communication-less announcement of breaking APIs), and strengthens that of CalVer (encouraging documentation and communication).

Sounds like I may need to create a FAQ for the calver.org site :)

peterjc commented 6 years ago

I mentioned another hybrid example on #5 using what I would call MAJOR.0Y.0M.0D in the CalVer style notation.