Hi Henri, 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 don't see a real different between stable and usable. Either a user can rely on a functionality or not. If you want to improve a part of the API without breaking compatibility, you may always deprecate the part that should no longer be used, because it will vanish in the next major release. This is what we normally do for a new release. This is e.g. what we've done with commons-io (although we improved the interface for generics). If it is a real redesign of the API (like lang3), we make it possible to use old and new versions side-by-side with new package name and artifactId to avoid unresolvable dependency situations for our users. I am all for 'internal' packages. IMHO it is not necessary to name a package as 'internal' as long as it is clearly documented, but it is definitely a better indication. It's definitely the right approach to exclude internal packages from clirr, personally I'd even exclude internal packages from Javadoc. The risc of usage must be clear to every user. However, I don't believe that annotations will really help. I'd separate internal stiff on package boundary and anything else is part of the public API. If you start to mix different annotations within one package, all you get is confusion. Cheers, Jörg --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
