On Thu, May 3, 2012 at 10: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. It's not clear for me how we can keep backward compatibility when adding a new method to an interface. What do you put in legacy? > * 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. +1 Thanks, Marius > > 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 _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
