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, Henrib -- View this message in context: http://apache-commons.680414.n4.nabble.com/RELEASE-PROCESS-Stability-versus-usability-tp4150322p4156330.html Sent from the Commons - Dev mailing list archive at Nabble.com. --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
