On Feb 7, 2013, at 5:52 PM, Vincent Massol <[email protected]> wrote:
> 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). > " Interestingly a user points out the issue I had with using an annotation, see the comments in http://code.google.com/p/guava-libraries/wiki/Release10: Extract: " My understandig of @Beta is, that these are the higly unstable parts of guava, so I don't want to use them (and I guess most developers don't want to because why should anybody make his lives more difficult when moving to the next version). But how do I do that? I don't want to look all the time at the source code when programming to make sure I didn't use the beta parts. Code completion knows nothing about @Beta (and it shouldn't!). Hence I have to remove all the beta parts. But why should the user handle the repackaging thing when you can simple release two versions: a beta / instable version and a stable / release version. Simple as that. Anybody can use the version he likes. Other OSS projects handle this much better. The same goes vor versioning, naming, packaging, downloading, etc. E. g. I never had such fruitless discussions with Apache software (and in case Apache commons collection ever releases a "generified" version, I'll most certainly switch back to that). " Thanks -Vincent > 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
