Seeing this thread where we discuss about deprecations, I use this for asking if there is some action to take when looking into (1) I conducted a small research for some time ago.
There are tables containing what was deprecated and when. We have removed all deprecated code from 1.x and 2.x in CASSANDRA-18959. We have put "since" into all Deprecated annotations in (2) just to track when exactly it was deprecated. (I think we did a great job there as we have way easier job right now when we contemplate about what to do with it). We still have deprecated code from times of 3.x. If we go to release 6.0, by the rules mentioned here, does it mean that all code which was deprecated in 4.0 can be actually removed in 6.0? Hence, we can remove it all basically right now? (As trunk will be 6.0, right?) If we do not want to do that, in other words, we want to keep deprecated code from times of 3.x, does it mean that we are actually not following the rules we suggested there? If that is the case, since when exactly we will start to apply them? (1) https://issues.apache.org/jira/browse/CASSANDRA-18938 (2) https://issues.apache.org/jira/browse/CASSANDRA-18912 From: Josh McKenzie <jmcken...@apache.org> Date: Monday, 21 April 2025 at 15:20 To: Benedict <bened...@apache.org>, dev <dev@cassandra.apache.org> Subject: Re: [DISCUSS] How we version our releases EXTERNAL EMAIL - USE CAUTION when clicking links or attachments Honestly, excepting thrift support I can't remember something we removed from the system in this way so a lot of this is perhaps premature process optimization. And I agree w/you here Benedict; given we can shim in translation from new functionality to continue to support previous APIs (thinking JMX as an example) there's really no hard requirement to deprecate or drop things excepting the maintenance cost, developer availability, and complexity burden of carrying some of these things forward. That said, I think Joey's framework makes intuitive sense so definitely worth exploring here and having in the archive so if we face some challenges in this department in the future we have some prior art and thinking to start from. On Fri, Apr 18, 2025, at 4:17 PM, Benedict wrote: I’d much rather we agree to try NOT to deprecate or break things full stop. But once we decide there’s good reason to, I don’t think arbitrary lifetimes for a feature are really all that helpful are they? On 18 Apr 2025, at 20:03, Josh McKenzie <jmcken...@apache.org> wrote: I personally feel that patch level fixes should count as “next major” to avoid this problem. +1. Let me try and distill yours and Joey's thoughts: 1. Any release after a MAJOR.0.0 qualifies as MAJOR+1 in terms of deprecation 2. On deprecation, explain the path forward to users (move to different feature, stop using, etc) 3. On deprecation, log at WARN on usage of feature 4. 4 levels of impact: * High (CQL API). Deprecation window > of 3 majors or 4 years. Can be extended w/consensus * Medium (.yml, mgt api, virtual table): > of 2 majors or 1 year * Low (param, perf tweak, etc): log warning, keep to T-1 deprecate-then-remove * Experimental: Removable at any time. 1. For high and medium, dev ML w/[DISCUSS] is required for deprecation and for removal respectively All seems reasonable to me. Curious to hear what others think. On Fri, Apr 18, 2025, at 2:02 PM, David Capwell wrote: Assuming there's no major flaws in my reasoning above We can release 4.0.x today, while 5.0.x exists… so lets play with that We release 7.0.0, hooray !!! But during this we find a bug in 6.0.x that we back port, which deprecates something, so 6.0.x releases at the same time as 7.0.0… so can 7.0.0 delete the change as it was part of 6.x line? I personally feel that patch level fixes should count as “next major” to avoid this problem. It also makes things very clear… w/e we did in N.0.0 is what matters, everything after is after that point and falls into (N + 1).0.0 We can also say that deprecation is frozen in N.0.0 and can only happen on trunk… no back ports allowed… both my recommendation and “no back ports” have the same effect. On Apr 18, 2025, at 5: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<mailto: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<mailto: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<mailto: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?
