You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@hbase.apache.org by "张铎 (Duo Zhang)" <pa...@gmail.com> on 2017/04/01 00:30:34 UTC
Re: About the InterfaceStability annotation for public API
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) <pa...@gmail.com>:
> Filed https://issues.apache.org/jira/browse/HBASE-17828
>
> 2017-03-21 8:36 GMT+08:00 张铎(Duo Zhang) <pa...@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 <je...@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 <ca...@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 <bu...@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 <zh...@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.
>>> > >
>>> >
>>>
>>
>>
>
Re: About the InterfaceStability annotation for public API
Posted by Jerry He <je...@gmail.com>.
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) <pa...@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) <pa...@gmail.com>:
>
> > Filed https://issues.apache.org/jira/browse/HBASE-17828
> >
> > 2017-03-21 8:36 GMT+08:00 张铎(Duo Zhang) <pa...@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 <je...@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 <ca...@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 <bu...@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 <zh...@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.
> >>> > >
> >>> >
> >>>
> >>
> >>
> >
>