On 4 December 2011 10:41, henrib <hen...@apache.org> wrote: > Keeping track as it evolves based on feedback; > > Goal is to allow easy definition, usage and check of stable APIs.
+1, agree that we need to be clearer about what the intended external API is. > An annotation and a package naming convention allow the project developer to > clearly state when a class/method/field is not part of the stable contract > despite a public/protected declaration but only of the internal part of the > project. +1 > @internal annotated class/method or *internal* package mean "use this at > your own maintenance cost"; those are not part of the "public" API. They can > be used and extended but are subject to change between versions without > @deprecated annotations. +1. I prefer the use of a separate internal/experimental package name; seems much more obvious than an embedded annotation. Also much more obvious when setting up Clirr exclusions. I think it's worth having both internal and experimental packages (and annotations): - internal = not likely ever to be part of the external API - experimental = may one day become part of the external API However, I'm not yet sure how we get around the binary incompatibilities that result from renaming a package to internal or experimental (the reverse should be OK, as we don't promise anything) > Those annotations and conventions should allow feeding a clirr report with > the proper information to allow detection of unintended API breakage and may > even allow creating IDE plugins to warn about usage. Clirr can already be told to ignore packages and classes. If it were possible to control this via annotations, I would hope that the report would show which classes had been excluded from consideration. At least with explicit exclusions in the POM it's fairly easy to see this information in one place. --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
