hbase-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From 张铎(Duo Zhang) <palomino...@gmail.com>
Subject Re: About the InterfaceStability annotation for public API
Date Sat, 01 Apr 2017 00:30:34 GMT
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) <palomino219@gmail.com>:

> Filed https://issues.apache.org/jira/browse/HBASE-17828
>
> 2017-03-21 8:36 GMT+08:00 张铎(Duo Zhang) <palomino219@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 <jerryjch@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 <carp84@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 <busbey@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 <zhangduo@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.
>>> > >
>>> >
>>>
>>
>>
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message