hbase-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jerry He <jerry...@gmail.com>
Subject Re: About the InterfaceStability annotation for public API
Date Sat, 01 Apr 2017 00:53:44 GMT
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) <palomino219@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) <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