Filed https://issues.apache.org/jira/browse/HBASE-17828
2017-03-21 8:36 GMT+08:00 张铎(Duo Zhang) <palomino...@gmail.com>: > bq. If someone is > comfortable with the risk of an API that can change in minor or > maintenance releases, what's gained by calling it IA.Public + > IS.Evolving or Unstable rather than just labeling it IA.Private or > IA.LimitedPrivate? > > Indeed. We can not stop users use IA.Private classes if they are declared > as public class. The users take the risk by themselves. > > Anyway, seems we all agree that at least we need to update our > documentation. So let me open a issue first. We can continue the discussion > there. > > Thanks. > > 2017-03-21 4:27 GMT+08:00 Jerry He <jerry...@gmail.com>: > >> Just to bring up an alternative idea. >> The Spark InterfaceStability explicitly spells out what can or can not >> change from major or minor releases. (I was onto it recently). >> See [1] >> >> HBase is probably a more stable project that does not have to do the same. >> But it is also possible that we may have new features (i.e. AsyncClient, >> Backup, etc) that we want to evolve within a major release. >> We should see if we want to provide such flexibility via the >> InterfaceStability annotations and document it explicitly if yes. >> >> Thanks, >> >> Jerry >> >> >> 1. https://github.com/apache/spark/blob/master/common/tags/ >> src/main/java/org/apache/spark/annotation/InterfaceStability.java >> >> >> >> >> On Mon, Mar 20, 2017 at 10:46 AM, Yu Li <car...@gmail.com> wrote: >> >> > +1 on removing InterfaceStability annotation for IA.Public. Even more, >> is >> > it possible to forbid using these two annotations together in Yetus at >> > code-level if we are migrating to it (as mentioned in another thread)? >> > >> > For IA.Private or IA.LimitedPrivate, personally I think >> InterfaceStability >> > is still a useful annotation. >> > >> > Best Regards, >> > Yu >> > >> > On 20 March 2017 at 22:07, Sean Busbey <bus...@apache.org> wrote: >> > >> > > I really dislike having InterfaceStability markings on IA.Public >> > > interfaces, because to me it reads like us essentially saying we >> > > didn't invest enough time in deciding what something should look like >> > > before declaring it safe for downstream folks. If someone is >> > > comfortable with the risk of an API that can change in minor or >> > > maintenance releases, what's gained by calling it IA.Public + >> > > IS.Evolving or Unstable rather than just labeling it IA.Private or >> > > IA.LimitedPrivate? >> > > >> > > So I'd be +1 on updating our docs to state that InterfaceStability is >> > > just for IA.LimitedPrivate or even discontinuing our use of it >> > > entirely. >> > > >> > > On Sun, Mar 19, 2017 at 11:28 PM, Duo Zhang <zhang...@apache.org> >> wrote: >> > > > In the compatibility section of our refguide, the compatibility for >> > patch >> > > > version, minor version and major version is not related >> > > > to InterfaceStability annotation. The only place we mention it is >> for >> > > > Server-Side Limited API compatibility. >> > > > >> > > > And in the Developer Guidelines section, we say this >> > > > @InterfaceStability.Evolving >> > > > >> > > > Public packages marked as evolving may be changed, but it is >> > discouraged. >> > > > I think this is a little confusing, esepecially that the comment >> > > > of InterfaceStability also mentions the compatibility for patch, >> minor >> > > and >> > > > major release. >> > > > >> > > > For me, I think only InterfaceStability.Unstable is useful for >> public >> > > API. >> > > > It means the API is still experimental and will not respect the >> > > > compatibility rule. >> > > > >> > > > So here I suggest we just remove the InterfaceStability annoation >> for >> > the >> > > > classes which are marked as InterfaceAudience.Public, and change the >> > > > comment of InterfaceStability and also the refguide to be more >> > specific. >> > > > >> > > > Suggestions are welcomed. >> > > > >> > > > Thanks. >> > > >> > >> > >