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