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),
> 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?
>
