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 > > >> > > > > > > >> > > > > > >> > > > > >> > > > >> > > > > > >
