You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@hbase.apache.org by Duo Zhang <zh...@apache.org> on 2017/03/20 04:28:15 UTC
About the InterfaceStability annotation for public API
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.
Re: About the InterfaceStability annotation for public API
Posted by Jerry He <je...@gmail.com>.
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) <pa...@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) <pa...@gmail.com>:
>
> > Filed https://issues.apache.org/jira/browse/HBASE-17828
> >
> > 2017-03-21 8:36 GMT+08:00 张铎(Duo Zhang) <pa...@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 <je...@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 <ca...@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 <bu...@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 <zh...@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.
> >>> > >
> >>> >
> >>>
> >>
> >>
> >
>
Re: About the InterfaceStability annotation for public API
Posted by "张铎 (Duo Zhang)" <pa...@gmail.com>.
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) <pa...@gmail.com>:
> Filed https://issues.apache.org/jira/browse/HBASE-17828
>
> 2017-03-21 8:36 GMT+08:00 张铎(Duo Zhang) <pa...@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 <je...@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 <ca...@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 <bu...@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 <zh...@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.
>>> > >
>>> >
>>>
>>
>>
>
Re: About the InterfaceStability annotation for public API
Posted by "张铎 (Duo Zhang)" <pa...@gmail.com>.
Filed https://issues.apache.org/jira/browse/HBASE-17828
2017-03-21 8:36 GMT+08:00 张铎(Duo Zhang) <pa...@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 <je...@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 <ca...@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 <bu...@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 <zh...@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.
>> > >
>> >
>>
>
>
Re: About the InterfaceStability annotation for public API
Posted by "张铎 (Duo Zhang)" <pa...@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 <je...@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 <ca...@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 <bu...@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 <zh...@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.
> > >
> >
>
Re: About the InterfaceStability annotation for public API
Posted by Jerry He <je...@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 <ca...@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 <bu...@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 <zh...@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.
> >
>
Re: About the InterfaceStability annotation for public API
Posted by Yu Li <ca...@gmail.com>.
+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 <bu...@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 <zh...@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.
>
Re: About the InterfaceStability annotation for public API
Posted by Sean Busbey <bu...@apache.org>.
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 <zh...@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.