Mailing-List: contact dev-help@hbase.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@hbase.apache.org
MIME-Version: 1.0
In-Reply-To: <CAHkeaHWtrKm6bOaBkWieeeGiFsxS1JYjT_w=3KFM606DDxOuKQ@mail.gmail.com>
References: <CAAAYAnMYpzzLmMNWqLBOkAovX29UkSnmwB5vbT+ddkLgpEV8Ww@mail.gmail.com>
 <CAN5cbe66-oTmdMXcUZ1NgM-AozJSpnNBE34NNL6uRi6rNnZQAw@mail.gmail.com>
 <CAM7-19KPAejae4JPddy+8uoVJzBA-n5Ctnv7XXssJ6F8M6u32w@mail.gmail.com> <CAHkeaHWtrKm6bOaBkWieeeGiFsxS1JYjT_w=3KFM606DDxOuKQ@mail.gmail.com>
From: =?UTF-8?B?5byg6ZOOKER1byBaaGFuZyk=?= <palomino219@gmail.com>
Date: Tue, 21 Mar 2017 08:36:17 +0800
Message-ID: <CAAAYAnMxj7op2xRrQkHZMzRa+0b4tz+cv4y9itpAA=_NQCcm-w@mail.gmail.com>
Subject: Re: About the InterfaceStability annotation for public API
To: dev@hbase.apache.org
Content-Type: multipart/alternative; boundary=94eb2c191e9c0aa7f6054b32d5d1
archived-at: Tue, 21 Mar 2017 01:41:00 -0000

--94eb2c191e9c0aa7f6054b32d5d1
Content-Type: text/plain; charset=UTF-8

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.
> > >
> >
>

--94eb2c191e9c0aa7f6054b32d5d1--