TL;DR: I agree with Duo's proposal, that we keep the base rule in mind but allow exceptional case with adequate discussion and fine documentation.
First of all, I'd like to express my personal appreciation for the efforts spent on removing deprecated codes and bringing up the discussion. Secondly, I agree with Sean that the base rule has no problem, but the real problem is we're observing a (pretty much) slowing down on major release period, which causes deprecated codes live for much longer than it's ought to. Maybe it's a little bit off the track but should we start another thread discussing about our roadmap for 3.0 or even further? 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. 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 > >> > > > > > >> > > > > >> > > > >> > > >> > > >
