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?
