I feel like the "T-1" approach only really makes sense if there are additional time guarantees with features that have left experimental status. I agree it is good to shift our versions to the left (folks already treated the concatenation of major.minor as our major), but I agree with Benedict and others that we could accompany that with a compatibility statement. Maybe a version support policy could help folks be less concerned - just a starting point / idea in addition to our current policies around bug/security fixes:
Upgrades are well tested between adjacent major releases. When a release is cut we will signal the minimum version that can be safely upgraded to the new version. GA features remain supported and encouraged until deprecated in a major release. Deprecation means we encourage migration away from that feature and use of deprecated features will trigger WARN level logging. Removal of a GA feature after deprecation depends on the impact. After deprecation we consider three categories of breaking change: High-impact: A change likely to break many users in an unsafe way such as CQL API break. Absent a compelling reason we will maintain these for the greater of 4 (3?) major versions or 4 years. Furthermore, the community can request extensions to be considered on a case by case basis. Medium-impact: A change likely to break users but in a minimal or safe way such as cassandra.yaml or management API (jmx/virtual table) change. Removal will, when applicable, crash on invalid values and/or unknown values if that improves safety. Such features will be maintained for the greater of 1 additional major version or 1 year after deprecation. Low-impact: A rarely used option or parameter that e.g. changes the performance or behavior but is not expected to break users. We will log a warning of the stale configuration during the deprecation but make no significant efforts beyond that. Experimental features may be disabled or removed in any major release, if they are it will be noted in the release notes. Use experimental features with caution and understanding of this. Just some thoughts/ideas, if we wanted we could maybe codify that any medium or high impact breaking change should be explicitly voted on or discussed, or we could just tell committers and ask if they can follow something like the above? -Joey On Fri, Apr 18, 2025 at 8:42 AM Josh McKenzie <jmcken...@apache.org> wrote: > One thing that would be great to be super clear about, if a patch release > deprecates a feature, does that act as if the next major deprecated it, or > the current major? > > Hm. So thinking this through, the deprecate-then-release model gives us 2 > affordances: > > 1. A minimum time horizon where something will be around but signaling > to users it's going away > 2. Predictability and the ability for users to plan on their > validation and changes to upgrade to a new release > > In your example David, we have 2 options to consider that mostly influence > point 1 above: > > 1. Deprecate in 6.0.1 means we can remove in 7.0.0 (deprecated in > major X, removed in major X+1, OR > 2. Deprecate in 6.0.1 rounds up and qualifies as "deprecated in next > major", i.e. 7.0.0, so we would remove in 8.0.0 > > In some hypothetical future where we released yearly, approach #1 gives > users a year to get ready to accommodate that deprecation, and approach #2 > gives them 2 years effectively. And that's the extreme case where someone's > aggressively looking to adopt new releases the day they come out. > > Assuming there's no major flaws in my reasoning above, I think I'd be > totally fine with us allowing deprecation of a feature in a patch release > and removal in the next major. Even the most extreme "abuse" of this system > for example: > - Version 6.0, 7.0, 8.0 are GA > - The day before we release 9.0, we deprecate a feature in 8.0.X, then > release 9.0 the next day with the feature removed > > The only people that would introduce pain to would be people running > 8.0.X-1, relying on a feature, who wanted to upgrade to 9.0 the next day. > Given how long validation and adoption times tend to be for deep infra > software like this, even that case doesn't really give me much heartburn. > We shouldn't do that of course, but even that extreme doesn't seem like > it'd cause too much pain. > > On Thu, Apr 17, 2025, at 2:53 PM, David Capwell wrote: > > Does it mean that one has to flag a feature as deprecated in the > unreleased version N, wait until when N is released (deprecating for one > major cycle), and then finally make the breaking change in N + 1? > > > My understanding is things are not different than before, we just don’t do > minors; which is what caused more confusion around this topic. > > Lets say we deprecate something in 6.0.0 (trunk), then 7.x must keep the > support, but 8.0.0 is free to delete it. > > Where the current process gets unclear is when you deprecate something in > 4.1, can you remove it in 6.0? > > One thing that would be great to be super clear about, if a patch release > deprecates a feature, does that act as if the next major deprecated it, or > the current major? Aka 6.0.1 deprecates something can we delete it in > 8.0.0 or is it only free to delete in 9.0.0? > > Also, I know we don’t plan to have 3 places, I just am using it out of > habit and to be clear with the current model =D > > On Apr 17, 2025, at 10:30 AM, Yifan Cai <yc25c...@gmail.com> wrote: > > Just realized that the other thread is for [vote]. Posting my question > here instead... > > I would like to get a better understanding of "but only for features that > have already been deprecated for one major release cycle." > > Does it mean that one has to flag a feature as deprecated in the > unreleased version N, wait until when N is released (deprecating for one > major cycle), and then finally make the breaking change in N + 1? > > Similarly, for a released version, say M (where trunk is at N), should the > author patch M to mark the feature as deprecated, and wait until N is > released (deprecating for one major release cycle), and introduce the > breaking in N + 1? > > > On Wed, Apr 16, 2025 at 5:15 AM Josh McKenzie <jmcken...@apache.org> > wrote: > > > Does this imply that each release is allowed to make breaking changes > (assuming they followed the “correct” deprecation process)? My first > instinct is to not like this > > Does the clarification in the earlier thread help shift your perspective / > address your concerns here David? > > Will leave this thread for another 24 hours to see if there's any other > concerns and call a vote if not. > > Thanks everyone for the engagement. > > On Fri, Apr 11, 2025, at 11:22 AM, Josh McKenzie wrote: > > So we avoid 6.1, 7.2, etc? Does this imply that each release is allowed > to make breaking changes (assuming they followed the “correct” deprecation > process)? > > Yes and no. > > A release can't make a breaking change *relative to the immediately > preceding release*, if something has been deprecated. > > A release *can* make a breaking change *from another actively supported > release* if it's not an adjacent release and the feature was signaled as > deprecated in the interim release. > > On Fri, Apr 11, 2025, at 10:39 AM, Jon Haddad wrote: > > +1. > > It's the proper signal to the community. A .1 release could still be done > as an exception, but I have a hard time thinking of a case other than > supporting a newer JDK without any other changes. > > On Fri, Apr 11, 2025 at 7:19 AM Jeremiah Jordan <jerem...@apache.org> > wrote: > > +1 from me. > No more wondering what the next version number will be. > No more wondering what version I can upgrade from to use the new release. > > -Jeremiah > > On Apr 10, 2025 at 3:54:13 PM, Josh McKenzie <jmcken...@apache.org> wrote: > > > This came up in the thread from Jon on "5.1 should be 6.0". > > I think it's important that our release versioning is clear and simple. > The current status quo of: > - Any .MINOR to next MAJOR is supported > - Any .MAJOR to next MAJOR is supported > - We reserve .MAJOR for API breaking changes > - except for when we get excited about a feature and want to .MAJOR to > signal that > - or we change JDK's and need to signal that > - or any of another slew of caveats that require digging into NEWS.txt > to see what the hell we're up to. :D > - And all of our CI pain that ensues from the above > > In my opinion the above is overly complex and could use simplification. I > also believe us re-litigating this on every release is a waste of time and > energy that could better be spent elsewhere on the project or in life. It's > also a signal about how confusing our release versioning has been for the > community. > > Let's leave aside the decision about whether we scope releases based on > time or based on features; let's keep this to the discussion about how we > version our releases. > > So here's what I'm thinking: a new release strategy that doesn't use > .MINOR of semver. Goals: > - Simplify versioning for end users > - Provide clearer contracts for users as to what they can expect in > releases > - Simplify support for us (CI, merges, etc) > - Clarify our public API deprecation process > > Structure / heuristic: > - Online upgrades are supported for all GA supported releases at time of > new .MAJOR > - T-1 releases are guaranteed API compatible > - We use a deprecate-then-remove strategy for API breaking changes > > This would translate into the following for our upcoming releases > (assuming we stick with 3 supported majors at any given time): > 6.0: > - 5.0, 4.1, 4.0 online upgrades are supported (grandfather window) > - We drop support for 4.0 > - API compatibility is guaranteed w/5.0 > 7.0: > - 6.0, 5.0, 4.1 online upgrades are supported (grandfather window) > - We drop support for 4.1 > - API compatibility is guaranteed w/6.0 > 8.0: > - 7.0, 6.0, 5.0 online upgrades are supported (fully on new paradigm) > - We drop support for 5.0 > - API compatibility guaranteed w/7.0 > > So: what do we think? > > > > >
