> 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: 1. High (CQL API). Deprecation window > of 3 majors or 4 years. Can be extended w/consensus 2. Medium (.yml, mgt api, virtual table): > of 2 majors or 1 year 3. Low (param, perf tweak, etc): log warning, keep to T-1 deprecate-then-remove 4. Experimental: Removable at any time. 5. 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> 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? >>>>>> >>>>> >>
