commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jörg Schaible <>
Subject Re: [RELEASE PROCESS] Stability versus usability
Date Mon, 05 Dec 2011 22:14:53 GMT
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.


To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message