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: <CAAAYAnMxj7op2xRrQkHZMzRa+0b4tz+cv4y9itpAA=_NQCcm-w@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> <CAAAYAnMxj7op2xRrQkHZMzRa+0b4tz+cv4y9itpAA=_NQCcm-w@mail.gmail.com>
From: =?UTF-8?B?5byg6ZOOKER1byBaaGFuZyk=?= <palomino219@gmail.com>
Date: Fri, 24 Mar 2017 09:48:49 +0800
Message-ID: <CAAAYAnPC-gEKwfr0EoQMp2pV8+zugovQ8uUE4EorhJf-E_UqsQ@mail.gmail.com>
Subject: Re: About the InterfaceStability annotation for public API
To: dev@hbase.apache.org
Content-Type: multipart/alternative; boundary=94eb2c1b2df2f3e83d054b703147
archived-at: Fri, 24 Mar 2017 01:49:02 -0000

--94eb2c1b2df2f3e83d054b703147
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: quoted-printable

Filed https://issues.apache.org/jira/browse/HBASE-17828

2017-03-21 8:36 GMT+08:00 =E5=BC=A0=E9=93=8E(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 discussi=
on
> 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 sam=
e.
>> 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 lik=
e
>> > > 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 i=
s
>> > > 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 fo=
r
>> > 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 t=
he
>> > > > comment of InterfaceStability and also the refguide to be more
>> > specific.
>> > > >
>> > > > Suggestions are welcomed.
>> > > >
>> > > > Thanks.
>> > >
>> >
>>
>
>

--94eb2c1b2df2f3e83d054b703147--