Re: [DISCUSS] InterfaceStability with InterfaceAudience.Public
unsubscribe
On Wed, Sep 8, 2021 at 8:45 AM Bryan Beaudreault
wrote:
> Thank you both for your input. That seems reasonable to me. In terms of the
> PR I was working on, I decided to keep it as the more restrictive
> InterfaceAudience.Public. I also created
>
> https://urldefense.com/v3/__https://issues.apache.org/jira/browse/HBASE-26266__;!!DCbAVzZNrAf4!QOyfoMjEhLOeMPVcgbU4AmTIvLamD9jdOj0hz45u_1CCG85JEOAkYJVpOyG3YJqwOw$
> to improve our docs on
> this topic. I'll try to get to that when I have time, if no one else gets
> to it before me.
>
> On Thu, Sep 2, 2021 at 11:38 AM Sean Busbey wrote:
>
> > Our API is already too big to audit by hand for breakage. The limited
> > tooling we have for automatically scanning as a part of the release
> > process[1] only has the ability to cope with a single set of
> > annotation (i.e. it can do "filter to things that are IA.Public" and
> > it can't do "filter to things that are IA.Public and IS.Stable"). As a
> > practical matter I don't think we can reliably meet promises beyond
> > "everything IA.Public is stable".
> >
> > That practical limitation is why the current HBase dev docs call out
> > our difference from yetus javadocs.
> >
> > I like the idea of a IA.LimitedPrivate experimental as a way to have a
> > proving ground for APIs we intend to make public but we want a test
> > out period in a user facing release. It's a relatively low risk way
> > for us as a community to see if we and our users find the approach
> > useful compared to how we currently do things (front load API
> > discussions and then mark things public; if needed deprecate/remove if
> > it doesn't work out).
> >
> > On Thu, Sep 2, 2021 at 9:38 AM 张铎(Duo Zhang)
> > wrote:
> > >
> > > I think the current Compatibility Matrix for our IA.Public APIs is
> > already
> > > complicated enough, so adding IS annotation to the IA.Public APIs will
> > be a
> > > huge pain for our end users, so I suppose we should not do this.
> > > And it is a bit strange that, an IA.Public API is also marked as
> > > IS.Unsable, right? It seems to just tell users do not use it, as it
> will
> > be
> > > broken even in a patch release...
> > > So in general, I think we should change the javadoc for the IS
> > annotation,
> > > to mention that we do not IS annotation for IA.Public APIs, it should
> > > always be IS.Stable.
> > >
> > > But looking from the developer side, it is a true pain that, seems
> there
> > is
> > > no way for us to introduce 'experimental' APIs.
> > > So maybe we could add a new LP type called experimental, so these APIs
> > > could be marked IA.LimitedPrivate("Experimental") and we could use the
> IS
> > > annotation then.
> > >
> > > This could make developers life easier, but I still a bit worry that,
> > will
> > > end users actually use these 'Experimental' APIs? If no one will use it
> > > until it becomes IA.Public, then what's the value for doing this...
> > >
> > > Just my simple thoughts.
> > >
> > > Thanks.
> > >
> > > Bryan Beaudreault 于2021年9月1日周三
> > 上午9:41写道：
> > >
> > > > Hello devs,
> > > >
> > > > A recent discussion came up on slack related to a PR I'm working on
> > which
> > > > adds a new class annotated with InterfaceAudience.Public. It seems
> like
> > > > there's some disagreement in terms of what the
> > > > current documented expectations are for InterfaceStability in this
> > case,
> > > > and what expectations we might actually want. Specifically, should we
> > allow
> > > > annotating IA.Public classes with IS.Evolving or IS.Unstable?
> > > >
> > > > Below I quote two conflicting documents, and I'm curious how the
> group
> > > > thinks we should reconcile them. Before I do, I just wanted to put
> out
> > my
> > > > opinion that it feels like we should have some ability to push new
> > public
> > > > classes that might evolve; basically beta features that are part of a
> > > > normal release.
> > > >
> > > > In the dev docs (
> > > >
> https://urldefense.com/v3/__https://hbase.apache.org/book.html*hbase.client.api.surface__;Iw!!DCbAVzZNrAf4!QOyfoMjEhLOeMPVcgbU4AmTIvLamD9jdOj0hz45u_1CCG85JEOAkYJVpOyHUjfiiaQ$
> > <
> https://urldefense.com/v3/__https://hbase.apache.org/book.html*hbase.client.api.surface__;Iw!!DCbAVzZNrAf4!QOyfoMjEhLOeMPVcgbU4AmTIvLamD9jdOj0hz45u_1CCG85JEOAkYJVpOyHUjfiiaQ$
> >
> > ),
> > > > there is this quote:
> > > >
> > > > IA.Public classes are inherently stable and adhere to our stability
> > > > guarantees relating to the type of upgrade (major, minor, or patch).
> > > > IA.LimitedPrivate classes should always be annotated with one of the
> > given
> > > > InterfaceStability values. If they are not, you should presume they
> are
> > > > IS.Unstable.
> > > > IA.Private classes should be considered implicitly unstable, with no
> > > > guarantee of stability between releases.
> > > >
> > > > On the other hand, the actual javadoc (
> > > >
> > > >
> >
>
Re: [DISCUSS] InterfaceStability with InterfaceAudience.Public
Thank you both for your input. That seems reasonable to me. In terms of the
PR I was working on, I decided to keep it as the more restrictive
InterfaceAudience.Public. I also created
https://issues.apache.org/jira/browse/HBASE-26266 to improve our docs on
this topic. I'll try to get to that when I have time, if no one else gets
to it before me.
On Thu, Sep 2, 2021 at 11:38 AM Sean Busbey wrote:
> Our API is already too big to audit by hand for breakage. The limited
> tooling we have for automatically scanning as a part of the release
> process[1] only has the ability to cope with a single set of
> annotation (i.e. it can do "filter to things that are IA.Public" and
> it can't do "filter to things that are IA.Public and IS.Stable"). As a
> practical matter I don't think we can reliably meet promises beyond
> "everything IA.Public is stable".
>
> That practical limitation is why the current HBase dev docs call out
> our difference from yetus javadocs.
>
> I like the idea of a IA.LimitedPrivate experimental as a way to have a
> proving ground for APIs we intend to make public but we want a test
> out period in a user facing release. It's a relatively low risk way
> for us as a community to see if we and our users find the approach
> useful compared to how we currently do things (front load API
> discussions and then mark things public; if needed deprecate/remove if
> it doesn't work out).
>
> On Thu, Sep 2, 2021 at 9:38 AM 张铎(Duo Zhang)
> wrote:
> >
> > I think the current Compatibility Matrix for our IA.Public APIs is
> already
> > complicated enough, so adding IS annotation to the IA.Public APIs will
> be a
> > huge pain for our end users, so I suppose we should not do this.
> > And it is a bit strange that, an IA.Public API is also marked as
> > IS.Unsable, right? It seems to just tell users do not use it, as it will
> be
> > broken even in a patch release...
> > So in general, I think we should change the javadoc for the IS
> annotation,
> > to mention that we do not IS annotation for IA.Public APIs, it should
> > always be IS.Stable.
> >
> > But looking from the developer side, it is a true pain that, seems there
> is
> > no way for us to introduce 'experimental' APIs.
> > So maybe we could add a new LP type called experimental, so these APIs
> > could be marked IA.LimitedPrivate("Experimental") and we could use the IS
> > annotation then.
> >
> > This could make developers life easier, but I still a bit worry that,
> will
> > end users actually use these 'Experimental' APIs? If no one will use it
> > until it becomes IA.Public, then what's the value for doing this...
> >
> > Just my simple thoughts.
> >
> > Thanks.
> >
> > Bryan Beaudreault 于2021年9月1日周三
> 上午9:41写道：
> >
> > > Hello devs,
> > >
> > > A recent discussion came up on slack related to a PR I'm working on
> which
> > > adds a new class annotated with InterfaceAudience.Public. It seems like
> > > there's some disagreement in terms of what the
> > > current documented expectations are for InterfaceStability in this
> case,
> > > and what expectations we might actually want. Specifically, should we
> allow
> > > annotating IA.Public classes with IS.Evolving or IS.Unstable?
> > >
> > > Below I quote two conflicting documents, and I'm curious how the group
> > > thinks we should reconcile them. Before I do, I just wanted to put out
> my
> > > opinion that it feels like we should have some ability to push new
> public
> > > classes that might evolve; basically beta features that are part of a
> > > normal release.
> > >
> > > In the dev docs (
> > > https://hbase.apache.org/book.html#hbase.client.api.surface
>
> ),
> > > there is this quote:
> > >
> > > IA.Public classes are inherently stable and adhere to our stability
> > > guarantees relating to the type of upgrade (major, minor, or patch).
> > > IA.LimitedPrivate classes should always be annotated with one of the
> given
> > > InterfaceStability values. If they are not, you should presume they are
> > > IS.Unstable.
> > > IA.Private classes should be considered implicitly unstable, with no
> > > guarantee of stability between releases.
> > >
> > > On the other hand, the actual javadoc (
> > >
> > >
> https://yetus.apache.org/documentation/in-progress/javadocs/org/apache/yetus/audience/InterfaceStability.htm
>
> > > )
> > > for InterfaceStability states:
> > >
> > > All classes that are annotated with InterfaceAudience.Public or
> > > InterfaceAudience.LimitedPrivate must have InterfaceStability
> annotation.
> > > Classes that are InterfaceAudience.Private are to be considered
> unstable
> > > unless a different InterfaceStability annotation states otherwise.
> > > Incompatible changes must not be made to classes marked as stable.
> > >
> > > One interpretation is that these are not in conflict, since one should
> > >
Re: [DISCUSS] InterfaceStability with InterfaceAudience.Public
Our API is already too big to audit by hand for breakage. The limited
tooling we have for automatically scanning as a part of the release
process[1] only has the ability to cope with a single set of
annotation (i.e. it can do "filter to things that are IA.Public" and
it can't do "filter to things that are IA.Public and IS.Stable"). As a
practical matter I don't think we can reliably meet promises beyond
"everything IA.Public is stable".
That practical limitation is why the current HBase dev docs call out
our difference from yetus javadocs.
I like the idea of a IA.LimitedPrivate experimental as a way to have a
proving ground for APIs we intend to make public but we want a test
out period in a user facing release. It's a relatively low risk way
for us as a community to see if we and our users find the approach
useful compared to how we currently do things (front load API
discussions and then mark things public; if needed deprecate/remove if
it doesn't work out).
On Thu, Sep 2, 2021 at 9:38 AM 张铎(Duo Zhang) wrote:
>
> I think the current Compatibility Matrix for our IA.Public APIs is already
> complicated enough, so adding IS annotation to the IA.Public APIs will be a
> huge pain for our end users, so I suppose we should not do this.
> And it is a bit strange that, an IA.Public API is also marked as
> IS.Unsable, right? It seems to just tell users do not use it, as it will be
> broken even in a patch release...
> So in general, I think we should change the javadoc for the IS annotation,
> to mention that we do not IS annotation for IA.Public APIs, it should
> always be IS.Stable.
>
> But looking from the developer side, it is a true pain that, seems there is
> no way for us to introduce 'experimental' APIs.
> So maybe we could add a new LP type called experimental, so these APIs
> could be marked IA.LimitedPrivate("Experimental") and we could use the IS
> annotation then.
>
> This could make developers life easier, but I still a bit worry that, will
> end users actually use these 'Experimental' APIs? If no one will use it
> until it becomes IA.Public, then what's the value for doing this...
>
> Just my simple thoughts.
>
> Thanks.
>
> Bryan Beaudreault 于2021年9月1日周三 上午9:41写道：
>
> > Hello devs,
> >
> > A recent discussion came up on slack related to a PR I'm working on which
> > adds a new class annotated with InterfaceAudience.Public. It seems like
> > there's some disagreement in terms of what the
> > current documented expectations are for InterfaceStability in this case,
> > and what expectations we might actually want. Specifically, should we allow
> > annotating IA.Public classes with IS.Evolving or IS.Unstable?
> >
> > Below I quote two conflicting documents, and I'm curious how the group
> > thinks we should reconcile them. Before I do, I just wanted to put out my
> > opinion that it feels like we should have some ability to push new public
> > classes that might evolve; basically beta features that are part of a
> > normal release.
> >
> > In the dev docs (
> > https://hbase.apache.org/book.html#hbase.client.api.surface),
> > there is this quote:
> >
> > IA.Public classes are inherently stable and adhere to our stability
> > guarantees relating to the type of upgrade (major, minor, or patch).
> > IA.LimitedPrivate classes should always be annotated with one of the given
> > InterfaceStability values. If they are not, you should presume they are
> > IS.Unstable.
> > IA.Private classes should be considered implicitly unstable, with no
> > guarantee of stability between releases.
> >
> > On the other hand, the actual javadoc (
> >
> > https://yetus.apache.org/documentation/in-progress/javadocs/org/apache/yetus/audience/InterfaceStability.htm
> > )
> > for InterfaceStability states:
> >
> > All classes that are annotated with InterfaceAudience.Public or
> > InterfaceAudience.LimitedPrivate must have InterfaceStability annotation.
> > Classes that are InterfaceAudience.Private are to be considered unstable
> > unless a different InterfaceStability annotation states otherwise.
> > Incompatible changes must not be made to classes marked as stable.
> >
> > One interpretation is that these are not in conflict, since one should
> > simply put IS.Stable on Public classes. But it seems like another
> > interpretation is that we just must put _any_ IS annotation.
> >
> > Thoughts?
> >
Re: [DISCUSS] InterfaceStability with InterfaceAudience.Public
I think the current Compatibility Matrix for our IA.Public APIs is already
complicated enough, so adding IS annotation to the IA.Public APIs will be a
huge pain for our end users, so I suppose we should not do this.
And it is a bit strange that, an IA.Public API is also marked as
IS.Unsable, right? It seems to just tell users do not use it, as it will be
broken even in a patch release...
So in general, I think we should change the javadoc for the IS annotation,
to mention that we do not IS annotation for IA.Public APIs, it should
always be IS.Stable.
But looking from the developer side, it is a true pain that, seems there is
no way for us to introduce 'experimental' APIs.
So maybe we could add a new LP type called experimental, so these APIs
could be marked IA.LimitedPrivate("Experimental") and we could use the IS
annotation then.
This could make developers life easier, but I still a bit worry that, will
end users actually use these 'Experimental' APIs? If no one will use it
until it becomes IA.Public, then what's the value for doing this...
Just my simple thoughts.
Thanks.
Bryan Beaudreault 于2021年9月1日周三 上午9:41写道：
> Hello devs,
>
> A recent discussion came up on slack related to a PR I'm working on which
> adds a new class annotated with InterfaceAudience.Public. It seems like
> there's some disagreement in terms of what the
> current documented expectations are for InterfaceStability in this case,
> and what expectations we might actually want. Specifically, should we allow
> annotating IA.Public classes with IS.Evolving or IS.Unstable?
>
> Below I quote two conflicting documents, and I'm curious how the group
> thinks we should reconcile them. Before I do, I just wanted to put out my
> opinion that it feels like we should have some ability to push new public
> classes that might evolve; basically beta features that are part of a
> normal release.
>
> In the dev docs (
> https://hbase.apache.org/book.html#hbase.client.api.surface),
> there is this quote:
>
> IA.Public classes are inherently stable and adhere to our stability
> guarantees relating to the type of upgrade (major, minor, or patch).
> IA.LimitedPrivate classes should always be annotated with one of the given
> InterfaceStability values. If they are not, you should presume they are
> IS.Unstable.
> IA.Private classes should be considered implicitly unstable, with no
> guarantee of stability between releases.
>
> On the other hand, the actual javadoc (
>
> https://yetus.apache.org/documentation/in-progress/javadocs/org/apache/yetus/audience/InterfaceStability.htm
> )
> for InterfaceStability states:
>
> All classes that are annotated with InterfaceAudience.Public or
> InterfaceAudience.LimitedPrivate must have InterfaceStability annotation.
> Classes that are InterfaceAudience.Private are to be considered unstable
> unless a different InterfaceStability annotation states otherwise.
> Incompatible changes must not be made to classes marked as stable.
>
> One interpretation is that these are not in conflict, since one should
> simply put IS.Stable on Public classes. But it seems like another
> interpretation is that we just must put _any_ IS annotation.
>
> Thoughts?
>
[DISCUSS] InterfaceStability with InterfaceAudience.Public
Hello devs, A recent discussion came up on slack related to a PR I'm working on which adds a new class annotated with InterfaceAudience.Public. It seems like there's some disagreement in terms of what the current documented expectations are for InterfaceStability in this case, and what expectations we might actually want. Specifically, should we allow annotating IA.Public classes with IS.Evolving or IS.Unstable? Below I quote two conflicting documents, and I'm curious how the group thinks we should reconcile them. Before I do, I just wanted to put out my opinion that it feels like we should have some ability to push new public classes that might evolve; basically beta features that are part of a normal release. In the dev docs (https://hbase.apache.org/book.html#hbase.client.api.surface), there is this quote: IA.Public classes are inherently stable and adhere to our stability guarantees relating to the type of upgrade (major, minor, or patch). IA.LimitedPrivate classes should always be annotated with one of the given InterfaceStability values. If they are not, you should presume they are IS.Unstable. IA.Private classes should be considered implicitly unstable, with no guarantee of stability between releases. On the other hand, the actual javadoc ( https://yetus.apache.org/documentation/in-progress/javadocs/org/apache/yetus/audience/InterfaceStability.htm) for InterfaceStability states: All classes that are annotated with InterfaceAudience.Public or InterfaceAudience.LimitedPrivate must have InterfaceStability annotation. Classes that are InterfaceAudience.Private are to be considered unstable unless a different InterfaceStability annotation states otherwise. Incompatible changes must not be made to classes marked as stable. One interpretation is that these are not in conflict, since one should simply put IS.Stable on Public classes. But it seems like another interpretation is that we just must put _any_ IS annotation. Thoughts?
