unsubscribe On Wed, Sep 8, 2021 at 8:45 AM Bryan Beaudreault <[email protected]> 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 <[email protected]> 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) <[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://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 ( > > > > > > > > > > > https://urldefense.com/v3/__https://yetus.apache.org/documentation/in-progress/javadocs/org/apache/yetus/audience/InterfaceStability.htm__;!!DCbAVzZNrAf4!QOyfoMjEhLOeMPVcgbU4AmTIvLamD9jdOj0hz45u_1CCG85JEOAkYJVpOyGJN6KCLA$ > > < > https://urldefense.com/v3/__https://yetus.apache.org/documentation/in-progress/javadocs/org/apache/yetus/audience/InterfaceStability.htm__;!!DCbAVzZNrAf4!QOyfoMjEhLOeMPVcgbU4AmTIvLamD9jdOj0hz45u_1CCG85JEOAkYJVpOyGJN6KCLA$ > > > > > > ) > > > > 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? > > > > > > >
