commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Phil Steitz <>
Subject Re: [RELEASE PROCESS] Stability versus usability
Date Sun, 04 Dec 2011 01:22:09 GMT
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.

> Best regards,
> Henri
> --
> View this message in context:
> Sent from the Commons - Dev mailing list archive at
> ---------------------------------------------------------------------
> To unsubscribe, e-mail:
> For additional commands, e-mail:

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

View raw message