commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From henrib <>
Subject Re: [RELEASE PROCESS] Stability versus usability
Date Sun, 04 Dec 2011 07:55:18 GMT

Phil Steitz wrote
> In practical terms, it might be hard to decide what to put where. 
> Can you provide some examples based on recent RCs?
When trying to release JEXL 2.1, the API was disrupted and the clirr report
was outputing lots of clutter.
As the dev, it became very hard to understand whether the change was
actually breaking the intended stable API or just some internal methods or
class. Then a lot of effort - thanks to sebb - had to be spent just to check
and amend the code to restore the contract.
The findbugs, cobertura, chekstyle reports mostly allow to assess quality, a
"usable" clirr report would give us a good view of "stability".

Phil Steitz wrote
> An easy baby step that I could personally get behind - and actually
> need in [math] - is adopting the .internal package name convention
For new packages or during major code overhaul, it definitely does the job.
But it might be unpractical and requires lots of code moving around; I'm
currently trying to achieve this with JEXL3 and it is a major refactor. Plus
it requires creating interfaces or abstract classes to clearly delineate the
API; it tilts the balance of effort towards stability and hinders the
ability to add features (in the same timeframe) thus slows down innovation.
The annotation would be convenient to (re)decorate code since it is very
lightweight, easy to use and control.
Instead of @unstable / @usable, may be an @internal annotation would carry
the proper information and would follow the same idea as the package name. 

@internal annotated class/method or *internal* package mean "use this at
your own maintenance cost"; it still allows "users" to code using them, does
not forcibly close extensibility thus preserve innovative contributions and
provides a clearer view of the stable contract. Seems like a win-win.

Best regards,

View this message in context:
Sent from the Commons - Dev mailing list archive at

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

View raw message