I’m late on this, but I had this thought. Why not have a minimum deprecation period of, say, 6 months, after which the API is eligible for depreciation. At that point, a deprecation can be proposed on a DISCUSS thread, with plenty of time given for discussion.
On Wed, Apr 24, 2019 at 9:56 PM Stack <st...@duboce.net> wrote: > On Wed, Apr 24, 2019 at 9:04 PM Yu Li <car...@gmail.com> 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) <palomino...@gmail.com> > 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) <palomino...@gmail.com> 于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 <reidddc...@outlook.com> 于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 <bus...@apache.org> > > > >> 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) <palomino...@gmail.com> > > > 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 <zyork.contribut...@gmail.com> 于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 < > > > lars.fran...@gmail.com> > > > >> > > 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 < > bus...@apache.org> > > > >> 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 > > > >> > > > > <jan.hentsc...@ultratendency.com> 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 > > > >> > > > > > > > >> > > > > > > >> > > > > > >> > > > > >> > > > > > > > > > >
