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). 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
Now the only problem I see with the above is that it would be hard to 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
