commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ralph Goers <>
Subject Re: [RELEASE PROCESS] Stability versus usability
Date Sun, 04 Dec 2011 08:58:42 GMT
The part I'm struggling with is that if these are annotations vs just javadoc tags then I would
expect some kind of either compile time or runtime behavior (or both).  It seems that you
are proposing javadoc tags instead?  If not what behavior would the annotations cause?


On Dec 3, 2011, at 5:22 PM, Phil Steitz wrote:

> 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:
>> 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:

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

View raw message