UPGRADING link in README is broken

[fguillen]

• https://github.com/mbleigh/acts-as-taggable-on/blob/master/UPGRADING.md

[seuros]

Upgrading.md was pretty outdated and was required at a previous breaking change.

[carlwiedemann]

Friendly bump. I'm working a project that needs to migrate from 8.x to 10.x.

Is there a tl;dr for the breaking changes for 8.x -> 9.x and 9.x -> 10.x?

Because no "breaking changes" are listed in https://github.com/mbleigh/acts-as-taggable-on/blob/master/CHANGELOG.md

Thanks in advance for any help you can provide.

[seuros]

Those version only had ruby or rails versions support.

The changes are documented

[carlwiedemann]

Let me clarify what I mean. See the attached screenshot.

10.x and 9.x are major versions. Major versions are defined by having breaking changes. But the CHANGELOG does not mention "Breaking Changes" -- the last time "Breaking Changes" is mentioned in the CHANGELOG was for 6.0.0

So it isn't clear what changes are "breaking" for these major versions. That is my concern. Does it make sense now?

---

[seuros]

Thank you for clarifying your point.

Major version upgrade is not defined by "MUST" have breaking changes, but by "MAY" have them.

If a backward incompatible changes are introduced to the public API, the version MUST be major bumped.

Version 10 loosened the dependency on ActiveRecord, making it compatible with V 7.1.

Suppose you were testing your application across different versions of Rails, and you verified that version 9.0.x does not support Rails 7.1. It would a surprise for version 9.1 to suddenly offer support for it without undergoing a major version update.

I started to use a github release workflow in the different gems i maintain, so the change-log will be more descriptive in the future.

[carlwiedemann]

I started to use a github release workflow in the different gems i maintain, so the change-log will be more descriptive in the future.

Ok, I appreciate your consideration. :)

Major version upgrade is not defined by "MUST" have breaking changes, but by "MAY" have them.

This was a surprise for me to read, so I am curious where this statement originates from. I don't believe this is part of the SemVer specification. Do you believe it is? If so, can you point to the part of the specification that supports your belief? Otherwise, can you say more about what has influenced this idea?

It would a surprise for version 9.1 to suddenly offer support for it without undergoing a major version update.

If it is helpful, I'd like to offer my own view: This example would not be a surprise for me. Adding support for a library is not a breaking change, by definition, and would be a "feature" addition. No consuming codebase would be broken by moving from 9.0.x to 9.1 as you have described. So I would be perfectly happy with seeing support for Rails 7.1 in a minor release rather than a major release.

Instead, when major version changes are made without breaking changes, then it is unclear to me whether the CHANGELOG is indeed accurate. This is my current situation. I am looking at this gem having multiple major version bumps, but the CHANGELOG does not describe them. So it isn't clear to me whether there are indeed breaking changes that the CHANGELOG is missing (as I have seen this happen many other times with other gems). Instead, as you now describe, the definition of "major" here is more liberal than I traditionally understand SemVer to decree. After all, the first line in the SemVer summary is "MAJOR version when you make incompatible API changes".

I just wanted to offer this feedback to you, because I know other programmers like myself who take this conservative view toward versioning. I hope it is helpful, and perhaps in the future you may consider only bumping major versions for changes that are indeed breaking.

Nevertheless, thank you for your timely responses. In the end, I am relieved to learn that there are no breaking changes for moving from 8.x to 10.x :)

[akostadinov]

Major version X (X.y.z | X > 0) MUST be incremented if any backward incompatible changes are introduced to the public API. It MAY also include minor and patch level changes. Patch and minor versions MUST be reset to 0 when major version is incremented.

It reads that you have to increment if you introduce such changes but it doesn't say that you cannot increment it otherwise.

A developer team can decide if a new major version is mandated. Reasons might be major refactoring, major new features, etc. etc. Maybe API didn't change but due to changed code, one can't be fully assured that everything retained behavior and no bug were introduced.

Why should one break the API just to increment the major version? ;)

[carlwiedemann]

Why should one break the API just to increment the major version? ;)

The definition of the word "semantic" is "relating to meaning in language or logic." In SemVer each version type, is intended to have a specific meaning, namely major.minor.patch == breaking.feature.fix == backward-incompatible-change.backward-compatible-enhancement.backward-compatible-bugfix

Unfortunately the word "major" has many meanings in English -- it usually means "significant" in common speech. But that is not its intended meaning in the parlance of SemVer, in my understanding, and I believe the parlance offers quite a bit of utility since one can glance at a version string right away and know what to expect

More unfortunately: I don't think the authors of the SemVer spec have been as rigorous about enforcing this as they should be. And so what results are conversations like this one we are having now.

I have some interest in pushing for a more rigorous adherence of these things, so I tend to end up in these conversations. My hope is that I find birds-of-a-feather who will see things from the same point of view.

I'm willing to change my mind if I'm offered a compelling counterargument, but most arguments aren't very compelling, and rely on sentimentality or the various meanings the words "major/minor/patch" can have.

All said, there are many significant projects that seem to simply do whatever they want (the Linux kernel being perhaps the most prominent example). It's possible that this gem is more in that camp. But I thought I'd at least make the case otherwise.

[akostadinov]

I'm willing to change my mind if I'm offered a compelling counterargument, but most arguments aren't very compelling

If potential unknown compatibilities and bugs because of big changes that are not supposed to be breaking but carry the risk, are not a compelling argument for you, I don't see what would be compelling to you. Why don't you create a fork of semver (e.g. semver strict) and see how is it being adopted?

[seuros]

Strictver

[carlwiedemann]

Yes, I am leaning in that direction.

[carlwiedemann]

potential unknown compatibilities and bugs because of big changes that are not supposed to be breaking but carry the risk

To be clear: This risk exists at all times, regardless of whether a change is viewed as “big” or not. A project could have a 1-line change that all maintainers believe is innocuous, but in fact breaks existing code or creates a huge security vulnerability. I’ve seen it happen before.

To paraphrase Dijkstra: “testing can only show the presence of bugs, never the absence of bugs.” If it is deemed wise to increment a major version due to caution, wouldn’t it follow that the wisest choice of all is to increment a major version for every change? That is where this logic leads us, I believe.

While you suggest I take the path toward “strict versioning” may I suggest that you take the path toward “sentimental versioning?” Because that is what you are actually describing — increments based on qualitative perceptions, rather than hard semantics & defined meaning.

If this is where our paths diverge, some good news for you is your path currently enjoys many fellow travelers (e.g. our Linux kernel friends mentioned earlier). My path may have fewer, but I believe it is the correct one. Time will tell. I’ll keep you updated on how “strictver” comes along (though I will workshop the name to be a bit more inviting). 😎

But at this point I believe we have diverted from the original intent of this issue, which I am partially (mostly?) to blame. Sorry for the noise. So I’ll leave this be and allow future conversation discuss the future of that UPGRADING link. Thanks for the illuminating and lively discussion. 👍

[akostadinov]

risk exists at all times, regardless of whether a change is viewed as “big” or not

@carlwiedemann , just FYI this is not an argument. Namely it is not an argument proving that big changes are (more) likely to produce backward incompatibilities. I would classify it as a straw man argument but I am ok to be corrected about which class if falls into.

btw often times downstream users rely on internal details, that are not supposed to be relied upon, but this is the reality. In a perfect world this shouldn't happen and in a perfect world I would hands down agree with your position. Maybe at least we share the opinion that it is sometimes annoying that we don't live in such a world.