On 12/2/11 3:45 PM, henrib wrote: > It seems to me we have a hard time allowing both stability and usability. > Stability of APIs does not contradict usability of the library, at least > should not. > > Some of us are looking for very long term/stable/high-quality solutions > because they need to aggregate lost of components, the stability users. > Others are looking for best-of-breed/narrow scope/malleable libraries a with > a guaranteed quality, the usability users. > Thus the importance of clearly stating in our libraries what is 'stable' and > what is 'usable'. > The expressiveness in the language itself is not enough to properly describe > the contract made regarding each party; i.e. sometimes things have to be > public but should not be considered part of the API that follow the > major,minor - deprecation. > I believe we can come up with a set of agreeable rules to please both > "camps" be through some naming convention in packages and annotations. > > As an kickstart proposal, may be something as simple as 2 annotations > actually could be enough: @stable, @usable. > @stable meaning the contract this API represents will not change without > being first @deprecated > @usable meaning this API is valid for this major version but may change in > each minor with no warning > We might also use a clear 'internal' sub-package name as a frontier > delimiter on the same rule. > > Thoughts ?
I applaud the initiative and creative suggestion above. I wonder, though, what users would make of it. My first thought as a user would be to avoid ever using the "unstable" stuff but I can imagine scenarios where I might. In practical terms, it might be hard to decide what to put where. Can you provide some examples based on recent RCs? An easy baby step that I could personally get behind - and actually need in [math] - is adopting the .internal package name convention for classes that need to be public because they are used in multiple packages, but which are not intended for use by external applications and effectively exempt from version compatibility requirements. That could by itself provide a workaround for a lot of these issues. Phil > Best regards, > Henri > > -- > View this message in context: > http://apache-commons.680414.n4.nabble.com/RELEASE-PROCESS-Stability-versus-usability-tp4150322p4150322.html > Sent from the Commons - Dev mailing list archive at Nabble.com. > > --------------------------------------------------------------------- > To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org > For additional commands, e-mail: dev-h...@commons.apache.org > > --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
