FWIW Guava is using a @Beta annotation: http://code.google.com/p/guava-libraries/
Extract: " APIs marked with the @Beta annotation at the class or method level are subject to change. They can be modified in any way, or even removed, in any major release. If your code is a library itself (i.e. it is used on the CLASSPATH of users outside your own control), you should not use beta APIs, unless you repackage them (e.g. using ProGuard). Here is a current list of all the beta APIs. Serialized forms of ALL objects are subject to change. Do not persist these and assume they can be read by a future version of the library. Deprecated non-beta APIs will be removed eighteen months after the release in which they are first deprecated. You must fix your usages before this time. If you don't, any manner of breakage might result (you are not guaranteed a compilation error). " Thanks -Vincent On May 3, 2012, at 9:47 AM, Vincent Massol <[email protected]> wrote: > Hi devs, > > We have recently voted a rule where we said that we will do the following: > * Always deprecate APIs > * Always move them to Legacy modules > * And when there's a technical issue to moving stuff to the Legacy module, > only then, send a VOTE to remove an API > (see http://markmail.org/message/tino4ngttflc5i3s). > > This means that from now on (starting on 26th of April 2012) we're not > allowed to put excludes in CLIRR. > > However I've seen that we have added some CLIRR excludes after the vote was > passed. > > I believe that the main issue we have is for "young" APIs that are not > considered stable. > > Proposal 1: Internal package > ========= > > * Young APIs must be located in the "internal" package till they become > stable. I propose "internal" to reuse an existing package that we filter when > testing for CLIRR. "internal" means that users should not use this API > because it's considered unstable and can change at any time. > * When a Young API is considered stable enough and we want to open it to > public consumption then we move it from "internal" to its target package > (that's easy to with IDEs). From that point forward any changes to them goes > through the standard mechanism of deprecation/legacy. > * If we want to add a new method to an existing public API then this should > not be considered a "young" API. It's just an addition to an existing API and > thus goes directly to the deprecation/legacy cycle. > * We need to be careful to isolate "young" APIs from public API so that users > don't inadvertently use "young" unstable APIs by mistake. If not possible > then directly go through the deprecation/legacy cycle. > > The advantage of this proposal is that it doesn't change our current > practices and is very easy to verify through CLIRR. > > Proposal 2: Experimental package > ========= > > Another possibility I can think of is to introduce a new "experimental" > package instead of reusing the "internal" one. It has the advantage of being > able to follow "young" APIs and ensure they don't stay in that state > indefinitely, while still allowing the user who uses it to notice it's > experimental. > > Proposal 3: Experimental Annotation > ========= > > Another idea is to just use an @Experimental javadoc tag for experimental > code. It has the advantage of using the target package but it has drawbacks: > * It's impossible for users to notice that they're using Experimental APIs > since when they import a class they won't see anything that'll tell them > they're using a "young" API > * It's almost impossible to tell CLIRR to exclude those APIs from its checks. > The only way to do this is to modify the source code of the CLIRR plugin > AFAIK. Thus we would need to exclude those manually using CLIRR excludes and > thus before we release we would need to go over the full list of CLIRR > excludes to ensure the excludes listed are only for "young" APIs marked > "experimental". > > Note that I mentioned javadoc tag and not annotation because I believe we > need to add information about when the Experimental API was first introduced > so that we eventually move it as a proper API by removing the Experimental > tag. Maybe we would need a rule such as: keep that tag for less or equal to 3 > full minor releases (i.e. 6 months). > > WDYT? Any other idea? > > Thanks > -Vincent > _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
