I really dislike having InterfaceStability markings on IA.Public interfaces, because to me it reads like us essentially saying we didn't invest enough time in deciding what something should look like before declaring it safe for downstream folks. If someone is comfortable with the risk of an API that can change in minor or maintenance releases, what's gained by calling it IA.Public + IS.Evolving or Unstable rather than just labeling it IA.Private or IA.LimitedPrivate?
So I'd be +1 on updating our docs to state that InterfaceStability is just for IA.LimitedPrivate or even discontinuing our use of it entirely. On Sun, Mar 19, 2017 at 11:28 PM, Duo Zhang <zhang...@apache.org> wrote: > In the compatibility section of our refguide, the compatibility for patch > version, minor version and major version is not related > to InterfaceStability annotation. The only place we mention it is for > Server-Side Limited API compatibility. > > And in the Developer Guidelines section, we say this > @InterfaceStability.Evolving > > Public packages marked as evolving may be changed, but it is discouraged. > I think this is a little confusing, esepecially that the comment > of InterfaceStability also mentions the compatibility for patch, minor and > major release. > > For me, I think only InterfaceStability.Unstable is useful for public API. > It means the API is still experimental and will not respect the > compatibility rule. > > So here I suggest we just remove the InterfaceStability annoation for the > classes which are marked as InterfaceAudience.Public, and change the > comment of InterfaceStability and also the refguide to be more specific. > > Suggestions are welcomed. > > Thanks.
