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) <[email protected]> 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 <[email protected]> 于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? > >
