On Fri, Feb 8, 2013 at 11:42 AM, Vincent Massol <[email protected]> wrote: > > 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?
Ok for me. > > 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 -- Thomas Mortagne _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
