On Feb 8, 2013, at 11:18 AM, Vincent Massol <[email protected]> wrote:
> > 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). > " Actually, reading further it seems only one user has an issue with the @Beta annotation and others find it acceptable. ok so here's the summary of the brainstorming so far: * Proposal 1 (internal package): - Vincent - Marius * Proposal 2 (experimental package) - Caleb * Proposal 3 (@Beta/@Experimental annotation) - Thomas - Edy * Other proposal - Denis (use 1) for small changes and only use RN to mark new module as experimental) Note that with proposal 3 we also need to remember 2 things: - we'll need to add CLIRR excludes but that can be done globally using the global exclude so not too painful - we'll need to detail how long is the @Beta annotation supposed to stay. If it stays forever it's the same syndrome as never releasing a 1.0 version which doesn't help because people will use it in production anyway if it's too long to be 1.0. So proposal 3 needs to have a max timeframe. IMO a full cycle would be a good max time to remain @Beta annotations. So if you add the @Beta in version N.P we have to remove it before N+2.0 (in practice that's a max time of 1.5 years). We could also say N+1.P but it's harder to remember since it means verifying at each release whereas N+1.P means verifying only once. Personally I'm ok to try option 3 since I'd like to make progress on this. WDYT? Thanks -Vincent > 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
