On May 3, 2012, at 2:47 PM, Marius Dumitru Florea wrote: > 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?
Yep, I have no solution for this except adding a new interface that extends the old one and adds new APIs which means doing an instanceof in code requiring access to the new methods… The other idea but this is a bit science-fiction would to make the xwiki runtime a "polymorphic runtime" (™) ;) This means: * At runtime, use Byteman or a tool that can change bytecode and when loading a Class inject behavior. For example if a Job class had a new method MMM added, loading a class implementing Job would add a default implementation for MMM if such a method doesn't already exist. In short this means bringing our compile time aspects to runtime. That's probably not very easy to do. Ideas anyone? Thanks -Vincent >> * 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
