May I suggest that when we're at a point to switch to new JDK, JDK 9 adds optional attributes to deprecated annotation
"By default, we should try our best to keep the deprecated APIs for at least a whole major release. All committers should have this in mind, when there is patch which deprecates a public API, we should make sure that there is a @deprecated javadoc comment says on which version it is deprecated, and on which version it is expected to be removed." @Deprecated(since = "4.5", forRemoval = true) Floating this up with Yetus is probably even better. On Thu, Apr 25, 2019 at 12:16 PM Andrew Purtell <[email protected]> wrote: > Also I think a history of contribution of fixes or improvements for a > thing in the state I described should count as much as someone on hand > right at the time for immediate improvement. Either case shows real > interest in the thing. > > > > On Apr 25, 2019, at 9:10 AM, Andrew Purtell <[email protected]> > wrote: > > > > This is a good approach, I think. > > > > If something is incomplete or known to be broken, and no volunteer is > willing to work on it, then what choice do we have, really? Well, we can > opt to do nothing and perhaps at some future time someone shows up, that is > an option too, but if we want to take action without someone on hand > willing to invest in a fix, the right call and action any of us probably > has time to take is removal. > > > > > >> On Apr 25, 2019, at 4:09 AM, Sean Busbey <[email protected]> wrote: > >> > >> We're a do-acracy, which I think makes both of those things hard or > >> impractical. > >> > >> Someone has to be available to do releasing with a regular period for > >> X-month deprecation cycles to work. I doubt we can sustain e.g. > something > >> like "you have to find a dedicated RM for 6 months of monthly minor > >> releases if you want to deprecate something". > >> > >> Similarly, how important a given feature is to our downstream users is > >> important, but it's more important how many of them are willing to show > up > >> and do maintenance work on the feature. > >> > >> Take for example Distributed Log Replay. It was broken and either > needed to > >> be fixed or needed to go. It doesn't matter how many folks were using it > >> despite our warnings about it's correctness or stability. When the call > >> went out, no one showed up with the time to make it work correctly so it > >> got yanked. > >> > >> > >>> On Thu, Apr 25, 2019, 00:29 Misty Linville <[email protected]> wrote: > >>> > >>> For features, I think we would need to understand the popularity of a > given > >>> feature by our user base, and that might vary wildly by feature. Do you > >>> think it would be possible to generalize? > >>> > >>>>> On Wed, Apr 24, 2019 at 9:56 PM Stack <[email protected]> wrote: > >>>>> > >>>>> On Wed, Apr 24, 2019 at 9:04 PM Yu Li <[email protected]> wrote: > >>>>> > >>>>> ... > >>>>> Thirdly, besides API deprecation, I think we should also discuss > about > >>>> the > >>>>> rule for feature deprecation. We ever deprecated DLR, I could observe > >>>> some > >>>>> discussion on deprecating preemptive fast fail recently, and > >>> personally I > >>>>> think there're some more features with few usage but making code base > >>>>> complicated. > >>>>> > >>>>> > >>>> I like this suggestion. Lets start a new topic on stuff to remove. > >>>> > >>>> Thanks Yu Li, > >>>> S > >>>> > >>>> > >>>> > >>>> > >>>>> Lastly, I think we need to emphasize on adding the incompatible flag > >>> and > >>>>> release note to JIRA and updating document whenever a deprecated > >>>>> feature/API is removed, which IMHO is not followed quite well > recently. > >>>>> > >>>>> Thanks. > >>>>> > >>>>> Best Regards, > >>>>> Yu > >>>>> > >>>>> > >>>>> On Thu, 25 Apr 2019 at 10:24, 张铎(Duo Zhang) <[email protected]> > >>>> wrote: > >>>>> > >>>>>> Let's get a conclusion here? > >>>>>> > >>>>>> By default, we should try our best to keep the deprecated APIs for > at > >>>>> least > >>>>>> a whole major release. All committers should have this in mind, when > >>>>> there > >>>>>> is patch which deprecates a public API, we should make sure that > >>> there > >>>> is > >>>>>> a @deprecated javadoc comment says on which version it is > deprecated, > >>>> and > >>>>>> on which version it is expected to be removed. > >>>>>> > >>>>>> And due to the difficulties in real world, if you think the above > >>> rule > >>>>>> makes it really hard to maintain a clean and stable code base, you > >>> can > >>>>>> break the rule. But you should have a strong enough reason, and > >>> also, a > >>>>>> nice written release note, and also update the upgrading section in > >>> our > >>>>> ref > >>>>>> guide. > >>>>>> > >>>>>> Is this OK? > >>>>>> > >>>>>> Thanks. > >>>>>> > >>>>>> 张铎(Duo Zhang) <[email protected]> 于2019年4月24日周三 下午2:38写道： > >>>>>> > >>>>>>> Phoenix is a good example I'd say, we have done a lot of CP related > >>>>>>> changes before releasing 2.0.0. But until now, Phoenix still has > >>>>> troubles > >>>>>>> to work together with 2.x, although we have already fixed several > >>>>>>> compatibility issues... It shows that, usually people will take > >>> much > >>>>> care > >>>>>>> on the alpha and beta releases... > >>>>>>> > >>>>>>> Reid Chan <[email protected]> 于2019年4月24日周三 上午10:58写道： > >>>>>>> > >>>>>>>> > >>>>>>>> As a strong coupling system to HBase, Phoenix has always been the > >>>>> first > >>>>>>>> sufferer, not only client APIs, but also some internal APIs. > >>>>>>>> Maybe we can ask Phoenix dev team what do they think, and get some > >>>>>>>> thoughts from them. > >>>>>>>> > >>>>>>>> > >>>>>>>> -------------------------- > >>>>>>>> > >>>>>>>> Best regards, > >>>>>>>> R.C > >>>>>>>> > >>>>>>>> > >>>>>>>> > >>>>>>>> ________________________________________ > >>>>>>>> From: Sean Busbey <[email protected]> > >>>>>>>> Sent: 24 April 2019 10:16 > >>>>>>>> To: dev > >>>>>>>> Subject: Re: [DISCUSS] Handling removal of deprecated methods and > >>>>>> classes > >>>>>>>> > >>>>>>>> Isn't API stabilization what we have alpha and beta releases for? > >>>>>>>> > >>>>>>>> There was nearly a year between the first alpha version of 2.0.0 > >>> and > >>>>> the > >>>>>>>> GA > >>>>>>>> release. Surely that should be a reasonable window for "trying > >>> out" > >>>> a > >>>>>> new > >>>>>>>> major release. > >>>>>>>> > >>>>>>>> I don't like the idea of telling our downstreamers that they can't > >>>>>>>> "really" > >>>>>>>> use or rely on our major releases until several minor releases in. > >>>>>> Either > >>>>>>>> we should say "API locks at X.0.0" or we should say "any API > >>> change > >>>>>> might > >>>>>>>> happen at a major version". > >>>>>>>> > >>>>>>>> We can always document what went away between minor releases even > >>> if > >>>>> we > >>>>>>>> can't give a compile time warning in advance (e.g. for the 2.0.0 > >>> to > >>>>>> 3.0.0 > >>>>>>>> user in your example Duo). > >>>>>>>> > >>>>>>>> We ended up trying to do that for 2.0.0 because so much had > >>> changed > >>>>> from > >>>>>>>> 1.0.0. > >>>>>>>> > >>>>>>>> > >>>>>>>> On Tue, Apr 23, 2019, 20:51 张铎(Duo Zhang) <[email protected]> > >>>>>> wrote: > >>>>>>>> > >>>>>>>>> Ideally, we'd better keep the deprecated APIs for at least a > >>> whole > >>>>>> major > >>>>>>>>> version, that means user can upgrade to a new major release from > >>>> any > >>>>>>>> minor > >>>>>>>>> releases, without seeing the removal of any non-deprecated APIs. > >>>>>>>>> > >>>>>>>>> For example, if we deprecate a method in 2.1.0, and remove it in > >>>>>> 3.0.0, > >>>>>>>>> then the users who upgrade to 3.0.0 from 2.0.0 will see the > >>>> removal > >>>>> of > >>>>>>>> this > >>>>>>>>> method, although the method is not deprecated on 2.0.0. > >>>>>>>>> > >>>>>>>>> But considering the current status of our project(as Sean > >>>> mentioned > >>>>>>>> above), > >>>>>>>>> I do not think it is a good idea to fully follow the rule. One > >>>> more > >>>>>>>> thing > >>>>>>>>> is that, for a new major release, usually the code base is not > >>>>> stable > >>>>>>>>> enough, need to be polished. Ideally it will be stable enough > >>>> after > >>>>>> one > >>>>>>>> or > >>>>>>>>> two minor releases. This means we will introduced new APIs and > >>>>>>>> deprecated > >>>>>>>>> old APIs in these minor releases. I think this is because that > >>> we > >>>> do > >>>>>> not > >>>>>>>>> have enough test before making a new major release, but this is > >>> a > >>>>> dead > >>>>>>>> lock > >>>>>>>>> problem. If we do not publish a new major release, users will > >>> not > >>>>> try > >>>>>> it > >>>>>>>>> which means we can not get enough test, since HBase is widely > >>> used > >>>>>>>>> everywhere and the release manager can only test a small set of > >>>> core > >>>>>>>>> features... > >>>>>>>>> > >>>>>>>>> For me, I think a better way is to not follow the rule for the > >>>> first > >>>>>>>>> several releases, i.e, we are free to remove APIs in the next > >>>> major > >>>>>>>> release > >>>>>>>>> if they are deprecated in x.1.0 and x.2.0 releases. But once we > >>>>> think > >>>>>>>> the > >>>>>>>>> APIs are stable enough, we should follow the rule again, i.e, > >>>> newly > >>>>>>>>> deprecated APIs should be retained in the next major release. > >>> For > >>>>>>>> example, > >>>>>>>>> for 2.x release, I think the stable minor release would be 2.3.0 > >>>> or > >>>>>>>> 2.4.0, > >>>>>>>>> which means if the APIs you used are not deprecated in these > >>> minor > >>>>>>>> release, > >>>>>>>>> then you can confirm that you can still use it in the next major > >>>>>>>> release. > >>>>>>>>> But for minor releases before it, for example, 2.1.x and 2.0.x, > >>>>> you'd > >>>>>>>>> better upgrade to 2.3.0 or 2.4.0 first, as the APIs you used may > >>>>>>>> disappear > >>>>>>>>> even if they are not deprecated. > >>>>>>>>> > >>>>>>>>> And we can add the above words in the upgrading part in our ref > >>>>> guide. > >>>>>>>>> > >>>>>>>>> Thanks. > >>>>>>>>> > >>>>>>>>> Zach York <[email protected]> 于2019年4月24日周三 > >>> 上午3:04写道： > >>>>>>>>> > >>>>>>>>>> Always good to see the history of the discussion :) It looks > >>>> like > >>>>>>>> nothing > >>>>>>>>>> really was decided last time (use caution if removing before a > >>>>> full > >>>>>>>> major > >>>>>>>>>> version), hopefully we can come up with something more > >>>> descriptive > >>>>>>>> this > >>>>>>>>>> time. > >>>>>>>>>> > >>>>>>>>>> I think the idea of having a tag/annotation for detailing when > >>>> the > >>>>>>>>>> method/feature is set for removal is a cool idea that we > >>> should > >>>>>>>>> investigate > >>>>>>>>>> further. If every deprecated method/feature had such an > >>>>> annotation, > >>>>>> it > >>>>>>>>>> would be easy to build automation around generating release > >>>>>>>>>> notes/documentation on what was removed in a particular > >>> version > >>>>>>>> (instead > >>>>>>>>> of > >>>>>>>>>> relying on someone to manually update the release note/docs). > >>>>>>>>>> > >>>>>>>>>> I agree that major releases are taking a long time to release > >>>> and > >>>>>> that > >>>>>>>>>> causes deprecated features to hang around for a long time, > >>> but I > >>>>>> also > >>>>>>>>> feel > >>>>>>>>>> like moving it to >= 1 minor release is a bit too quick and > >>>> would > >>>>>> add > >>>>>>>> to > >>>>>>>>>> upgrade burden. Not everyone uses every minor version so they > >>>>> might > >>>>>> be > >>>>>>>>>> taken unaware by the change or be less likely to upgrade as > >>>>> quickly. > >>>>>>>>>> I'm not necessarily against shortening the time. Maybe there > >>> is > >>>>> some > >>>>>>>> sort > >>>>>>>>>> of middle ground (>=2 minor releases), but that gets a little > >>>>> muddy > >>>>>>>> and > >>>>>>>>>> would need to be documented heavily. > >>>>>>>>>> > >>>>>>>>>> Thanks, > >>>>>>>>>> Zach > >>>>>>>>>> > >>>>>>>>>> On Tue, Apr 23, 2019 at 9:37 AM Lars Francke < > >>>>>> [email protected]> > >>>>>>>>>> wrote: > >>>>>>>>>> > >>>>>>>>>>> We had this exact same discussion four years ago (I thought > >>> it > >>>>> was > >>>>>>>> last > >>>>>>>>>>> year :O ): < > >>>>>>>>>>> > >>>>>>>>>>> > >>>>>>>>>> > >>>>>>>>> > >>>>>>>> > >>>>>> > >>>>> > >>>> > >>> > https://lists.apache.org/thread.html/bbdbf135abe7d8a0a4e7e9563f0bdc3dd6b555a0d3cdc1b1fdd688c2@1427759561@%3Cdev.hbase.apache.org%3E > >>>>>>>>>>>> > >>>>>>>>>>> > >>>>>>>>>>> On Tue, Apr 23, 2019 at 6:32 PM Sean Busbey < > >>>> [email protected]> > >>>>>>>> wrote: > >>>>>>>>>>> > >>>>>>>>>>>> I have the same interpretation as stack. However, I think > >>>> the > >>>>>>>>>>>> expectation back when 1.0.0 was rolling out was that we'd > >>>>> have a > >>>>>>>>>>>> regular cadence of major releases to use for removing > >>> things > >>>>>> that > >>>>>>>> had > >>>>>>>>>>>> been deprecated. I don't think that cadence has actually > >>>>>> happened. > >>>>>>>>>>>> > >>>>>>>>>>>> For example, here's a set of major releases and how long > >>> it > >>>>> had > >>>>>>>> been > >>>>>>>>>>>> since the prior major release at the time it came out: > >>>>>>>>>>>> > >>>>>>>>>>>> * 0.94 - 4 months > >>>>>>>>>>>> * 0.96 - 1.5 years > >>>>>>>>>>>> * 0.98 - 4 months > >>>>>>>>>>>> * 1.0 - 1 year > >>>>>>>>>>>> * 2.0 - 3.25 years > >>>>>>>>>>>> > >>>>>>>>>>>> If we started a vote today 3.0 would be at 1 year. I > >>> suspect > >>>>>> it's > >>>>>>>>> more > >>>>>>>>>>>> likely to end up landing around the 2 year mark. > >>>>>>>>>>>> > >>>>>>>>>>>> Given this rate and the fact that we've made exceptions in > >>>> the > >>>>>>>> past > >>>>>>>>>>>> (e.g. removing things in 2.0 that were deprecated after > >>> 1.0 > >>>>> was > >>>>>>>>>>>> already out), should we change our behavior or change what > >>>> we > >>>>>>>>> document > >>>>>>>>>>>> to allow removal at a major version without such a long > >>> lead > >>>>>> time? > >>>>>>>>>>>> > >>>>>>>>>>>> On Tue, Apr 23, 2019 at 10:17 AM Jan Hentschel > >>>>>>>>>>>> <[email protected]> wrote: > >>>>>>>>>>>>> > >>>>>>>>>>>>> Hi everyone, > >>>>>>>>>>>>> > >>>>>>>>>>>>> in the PR for HBASE-22262< > >>>>>>>> https://github.com/apache/hbase/pull/162 > >>>>>>>>>> > >>>>>>>>>> we > >>>>>>>>>>>> noticed that there could be easily a misunderstanding on > >>>> when > >>>>> to > >>>>>>>>> remove > >>>>>>>>>>>> deprecated methods. In the book< > >>>>>>>>>>>> http://hbase.apache.org/book.html#hbase.versioning.post10 > >>>> > >>>> it > >>>>>> is > >>>>>>>>>>>> documented “an API needs to be deprecated for a major > >>>> version > >>>>>>>> before > >>>>>>>>> we > >>>>>>>>>>>> will change/remove it.”. As the discussion on the PR shows > >>>> it > >>>>>>>> leaves > >>>>>>>>>> some > >>>>>>>>>>>> room for interpretation and should be made more specific, > >>>>>>>> including > >>>>>>>>>> some > >>>>>>>>>>>> examples. I think we all agree that removing a method in > >>>> 3.0.0 > >>>>>> is > >>>>>>>> ok > >>>>>>>>>> when > >>>>>>>>>>>> it was deprecated back in 2.0.0, but what do we do with > >>>>> methods > >>>>>> or > >>>>>>>>>>> classes > >>>>>>>>>>>> which were deprecated in a minor or patch version? As an > >>>>>> example, > >>>>>>>> if > >>>>>>>>> we > >>>>>>>>>>>> deprecate a method in 2.3.0, should it be removed in 3.0.0 > >>>> or > >>>>>>>> 4.0.0? > >>>>>>>>>>>>> > >>>>>>>>>>>>> Best, Jan > >>>>>>>>>>>> > >>>>>>>>>>> > >>>>>>>>>> > >>>>>>>>> > >>>>>>>> > >>>>>>> > >>>>>> > >>>>> > >>>> > >>> >
