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 Fri, 24 Mar 2017 01:48:49 GMT
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