On Tue, Oct 23, 2012 at 2:17 PM, Vincent Massol <[email protected]> wrote: > Hi Edy, > > Thanks for joining in! :) > > See below > > On Oct 23, 2012, at 12:52 PM, Eduard Moraru <[email protected]> wrote: > >> Hi, >> >> I am +1 for option 3), but I would actually prefer it that, instead of >> adding a new annotation by ourselves (@Experimental), we reuse java's >> deprecation mechanism [1] (@Deprecated annotation + @deprecated javadoc). > > That's different. This is not about deprecated code, it's about new code, > i.e. the exact opposite :) > >> This way: >> - users will be warned directly in the IDE to stay away from those APIs > >> - the compiler and other existing tools will warn about using the APIs >> - we can specify additional details and explanations in the @deprecated >> javadoc >> - the APIs can be public so we don`t need to move them around afterwards >> and we can avoid possible problems related to this; we just remove the >> @Deprecated annotation (as already mentioned in the @Experimental case). >> - we avoid complexity and headaches by not letting the deprecation/legacy >> process get in the way of the development of the new feature > > Yes of course now personally I don't like 3 at all because it's very very > maintenance-oriented (clirr excludes for example) and is going to cause a big > mess: As I said in my original email the problem is that there's no rule to > remove @Experimental so what will happen is that you'll find @Experimental > code that stays in this state forever, 5 years after it's been started > because there are always stuff to improve (it's the "1.0 syndrome"). > > I'm personally very very close to -1 solution 3 because it's almost the same > as not doing anything. > > For me the only real answer is to do what Eclipse used to do (I don't know if > they still do it) which is to:
> - code defensively, i.e. always put new code in the internal package (FTR I > took this notion of internal from them, see > http://jakarta.apache.org/cactus/participating/apis.html) > - open up APIs based on need. This means that whenever someone (a user) needs > an API he reports it and we then open it (if we consider the API is stable at > the time and it's a valid need) > - once it's opened go through the deprecation strategy +1 On this topic we should decide what we do with script services. Do we apply the same strategy (keep internal until someone asks for it)? If not then, as Jerome pointed out in a different thread, we need to distinguish between script service interfaces and the rest of the component roles (APIs). Thanks, Marius > > Note that we've done that in a few places where we have component interfaces > that are internal ATM. It's a good strategy to stabilize an API. > > What we would need to do is in the Developer guide on xwiki.org make it more > visible that devs should not use internal package and if they miss an API to > ask at such place for one (we could even have a jira issue type for that). > > Thomas and Denis argued that it's hard to do so for new domains like the new > rights implementation. I still don't understand why. Could you guys explain > what would have been difficult with the strategy above? > >> Now the only problem I see with the above is that it would be hard to > > oh it's far from being the "only" problem ;) Just to cite 3 issues: > > - clirr excludes are very hard to manage/maintain and a pain > - when to move out of "young api" is not defined > - wrong semantic of deprecated > > Thanks > -Vincent > >> programatically generate a list of young APIs, since there is no clear >> differentiation between deprecated and young API (other than the comment in >> the @deprecated javadoc). I don`t know if this is such a big problem, since >> the main goal is to keep users from using the APIs (for a while at least), >> or, if they do, to make them aware that they will need to refactor in the >> coming future. >> >> Thanks, >> Eduard >> ---------- >> [1] >> http://docs.oracle.com/javase/1.5.0/docs/guide/javadoc/deprecation/deprecation.html >> >> On Thu, May 3, 2012 at 4:48 PM, Vincent Massol <[email protected]> wrote: >> >>> >>> On May 3, 2012, at 3:40 PM, Thomas Mortagne wrote: >>> >>>> On Thu, May 3, 2012 at 3:24 PM, Denis Gervalle <[email protected]> wrote: >>>>> On Thu, 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. >>>>>> >>>>> >>>>> This is not always so easy. It really depends on what we are working >>> on. If >>>>> this is a small, or minor addition, this should works, but for really >>> new >>>>> experimental features, this does not fit (ie: security component). >>> First, >>>>> you will mixup internal and experimental, which will not shows the >>> intends >>>>> and not helps collaborating on the new feature. Second, this will also >>>>> influence the place for tests, which will need to be moved later as >>> well. >>>>> Third, you will not see potential access issue (package access), since >>> you >>>>> will mix packages that will be later split. >>>>> >>>>> >>>>>> * 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. >>>>>> >>>>> >>>>> This should solve most of the above inconvenient, but I am not sure we >>>>> really need that for new feature. Declaring the feature as experimental >>> in >>>>> the RN should be enough IMO. >>>>> >>>>> >>>>>> >>>>>> 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). >>>>>> >>>>> >>>>> But you have titled Annotation, which is confusing ! >>> >>> Actually we can have an annotation, since we can pass a description string >>> :) >>> So using an annotation is better than a javadoc tag. >>> >>> It also allows to relatively easily list all experimental apis with a tool >>> that finds annotations statically. We're going to need this to put in the >>> RN the list of experimental APIs. >>> >>>>>> WDYT? Any other idea? >>>>>> >>>>> >>>>> I would be +0 for a mix of 1) and 2) depending on the situation, since >>> 3) >>>>> does not really help. I am not sure that cases motivating 2) really >>> need it >>>>> and that it is not overkill since recent major features are always >>> known to >>>>> be subject to some early deprecation and that we already list all >>>>> deprecation in the RN so you may adapt your code rather quickly. >>>> >>>> Pretty much the same concerns than Denis: it's not as easy as you >>>> think to change package of a big project like rights or extension >>>> manager all the sudden. >>>> >>>> But I would vote -1 for 1) and -0 for 2) which is a bit better. >>>> >>>> IMO 3) is enough even if not perfect either. >>>> >>>> Also about adding new methods, that's really not the main issue of an >>>> experimental API in which we can potentially rename a bunch of methods >>>> because of a design change and an old API has the exact same issue so >>>> none of the proposal help in any way for this. >>> >>> There's no issue with adding new methods with proposals 1 and 2 since >>> clirr will not even check them :) >>> With 3) it's harder since you'll need to manually add CLIRR excludes. The >>> problem with CLIRR excludes is that you can only exclude a full file thus >>> potentially hiding breakages. The other issue is that we'll need to review >>> all CLIRR excludes one by one to verify if they're valid (ie code tagged >>> experimental) or not (in which case deprecation+legacy should be used >>> instead). >>> >>> I'm fine with strategy 3) but it's really important to have a limit as to >>> how long an api remains experimental because otherwise we're going to have >>> a lot of experimental apis that will never make it user-public and users >>> are going to start using them and then be broken. >>> >>> 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 > > _______________________________________________ > devs mailing list > [email protected] > http://lists.xwiki.org/mailman/listinfo/devs _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
