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 <bus...@apache.org> 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) <palomino...@gmail.com>
> 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 <bbeaudrea...@hubspot.com.invalid> 于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
> <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
> <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?
> > >
>
