Looks fine. Incorporating another public dimension probably makes the version scheme too complex. Keep it simple.
Jerry On Fri, Mar 31, 2017 at 5:30 PM 张铎(Duo Zhang) <palomino...@gmail.com> wrote: > Some progress here. > > In HBASE-17857, a sub task of HBASE-17828, I've created a script to remove > all the IS annotations for the IA.Public API. And I've also changed the > IA.Public annotations for several classes which are marked as IS.Unstable > to IA.Private. We can change them back when we think they are stable > enough. > > The patch is ready to land. Will commit it today if no objections. > > Thanks. > > 2017-03-24 9:48 GMT+08:00 张铎(Duo Zhang) <palomino...@gmail.com>: > > > 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. > >>> > > > >>> > > >>> > >> > >> > > >
