Hi Vincent, I have the exact same reading then Thomas. The @since tag should not be use for anything else than what it is made for: notifying the user of any package/class/method at which point it has been introduced. A package/class/method is define by its canonical name, and any change in it is therefore another package/class/method, even if it has the exact same signature.
While I understand that this could have not been properly followed in the past, this is clearly a mistake, and it is mostly due to the lack of automation/check on these annotations. The removal of the @Unstable annotation has nothing to do with @since, and should not be mixed up. I found very annoying to see the need to know for sure the introduction time of the @Unstable annotation, simple to respect a rules we have only voted to avoid those @Unstable to be left for ever. Normally, the "owner" of the newly introduced API, should take care to remove those @Unstable as earlier as possible, and the maximum should only be reach in very rare cases. So, my feeling is that those rare case could be solved using Git history/blame if ever needed. So I am not in favor of any of your "new" options. I would simply clarify the rules for @since (if really needed for those not understanding the obvious). I also remind all committers that it is your responsibility to remove the @Unstable you have introduce in due time. If you really want to add new annotations, I would be far more interested to distinguish API and SPI, and provide them a different stability, allowing us more flexibility :) Thanks, On Tue, Feb 11, 2014 at 3:22 PM, Thomas Mortagne <[email protected]>wrote: > On Tue, Feb 11, 2014 at 3:19 PM, Thomas Mortagne > <[email protected]> wrote: > > On Tue, Feb 11, 2014 at 3:15 PM, [email protected] <[email protected]> > wrote: > >> > >> See below. > >> > >> On 11 Feb 2014 at 13:17:03, Marius Dumitru Florea ( > [email protected](mailto:[email protected])) > wrote: > >> > >>> I agree with Thomas and Denis, but I must admit that I haven't updated > >>> the @since version when I did refactorings in the past. I'll pay > >>> attention to this next time. > >>> > >>> Thanks, > >>> Marius > >>> > >>> On Mon, Feb 10, 2014 at 2:51 PM, Denis Gervalle wrote: > >>> > On Sun, Feb 9, 2014 at 11:16 PM, Thomas Mortagne > >>> > wrote: > >>> > > >>> >> On Sun, Feb 9, 2014 at 6:10 PM, [email protected] > >>> >> wrote: > >>> >> > Hi devs, > >>> >> > > >>> >> > I always ask myself this question so I think we need a common > agreement. > >>> >> > > >>> >> > So here's the question: > >>> >> > * I have added some code in version N and this I have a "@since > N" in > >>> >> the code > >>> >> > * In version M (M > N), I move the class/interface to a new > package > >>> >> > > >>> >> > Question: Do I change the @since annotation to "@since M" or not? > >>> >> > > >>> >> > 2 possibilities: > >>> >> > * Reasoning 1: it's a new class/interface since the FQN of the > >>> >> class/interface has changed and thus we should use "@since M" > >>> >> > * Reasoning 2: even though the FQN has changed it's still the > same code > >>> >> that was moved and from a user POV, it was still introduced in > version N > >>> >> and thus we should keep "@since N" > >>> >> > > >>> >> > WDYT? > >>> >> > > >>> >> > I'm hesitating. The most technically correct answer is Reasoning > 1 IMO > >>> >> but the most useful one is probably Reasoning 2 since the question > we wish > >>> >> to answer is probably: "when was this code first introduced?". > >>> >> > > >>> >> > Thus reasoning 2 seems slightly better to me. > >>> >> > >>> >> Big -1 for 2 which is totally out of context, @since indicate that > you > >>> >> can use that class or method since that version in you code and > >>> >> indicate you which version you are going to be compatible with. If > you > >>> >> change the class or method your can't keep the same @since. If you > >>> >> want to know since when the feature exist look at xwiki.org... > >>> >> > >>> > > >>> > I completely agree with Thomas, a -1 for 2) > >>> > I would add that if you want to know from where the code come from, > Git is > >>> > your best friend. > >> > >> <playing devil's advocate for the sake of the discussion> > >> > >> I don't fully agree with this. > >> > >> The point of the @since tag is exactly to NOT have to check in Git to > see when some code was introduced! And with your logic, the @since tag is > never needed at all since we can always check in Git, and it's as easy to > check in Git for Reasoning 1 than it is for Reasoning 2. > > > > The point of @since is to indicate since when a signature exist which > > means that 2 is completely wrong. I never talked about git, I don't > > care how you know since when a feature exist but please don't use > > @since which has a different meaning for that. > > > >> > >> If you start changing the @since then it makes it impossible to > properly remove the @Unstable annotations later on since for each @Unstable > annotation you'll need to do some deep Git archeology to reconstruct the > first time the API was introduced. > >> > >> Also, I can tell you that a lot of devs (the majority, if not 80%) have > been doing Reasoning 2 since the beginning of our usage of @since, since > it's the simplest thing to do and it's what you get by default if you don't > do anything... I know I did it, I know Marius did too and I'm pretty sure > others too. > >> > >> So to recap, my points are: > >> * If you need to find out when some class was moved in another package > you can always check Git and you don't need the @since that for this > >> * Reasoning 1 makes it almost impossible in practice to remove > @Unstable annotations > >> * Reasoning 2 is complex to implement (the proof being that for most of > our code it wasn't done) > >> > >> </playing devil's advocate for the sake of the discussion> > >> > >> Note that this discussion is important since we never formalized how to > use the @since annotation (it's not documented on > http://dev.xwiki.org/xwiki/bin/view/Community/DevelopmentPractices). > >> > >> Also note that > http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#@sincedoesn't > explain what to do when a class/interface is moved elsewhere. I > googled and couldn't find how other projects handle the since tag. > > It does no say it because it's obvious, if you change the package you > change the name, the class short name does not have any value in Java. > > >> > >> So taking everything into account we have the following options: > >> > >> A) Update the @since value when we move a class/interface to another > package. But force the @Unstable annotation to have a text specified (ATM > it's optional) with the rule of specifying when the API is introduced. For > example @Unstable("Introduced in 5.4M1"). > >> > >> B) Keep what we've been doing implicitly, which is to not change the > @since value when a class/interface is moved to another package and > consider that this @since tag corresponds to when the code was first > introduced independently of its class/interface location. In this case no > need to use a text for the @Unstable annotation. > >> > >> C) Use some other annotation like for example @Introduced("5.2") or > @Introduced in 5.2 (javadoc). > >> > >> As for automating the addition of the since tags, I couldn't find > anything good for us to use. FTR I found: > >> - > http://stackoverflow.com/questions/3417243/automatic-since-javadoc-tag-for-releasesbut > the maven plugin doesn't do magic. > >> - > http://help.eclipse.org/indigo/index.jsp?topic=%2Forg.eclipse.pde.doc.user%2Freference%2Fapi-tooling%2Fapi_since_tags.htm > >> > >> While I prefer A) which I find more technically correct I think it's > also a lot more work to enforce (in lots of places it means duplicating > information between @since and @unstable) so I'm hesitating, especially > since we've been doing B implicitly. > >> > >> Any idea/preference? > >> > >> Thanks > >> -Vincent > >> > >> > >>> > I take the occasion to also mention that it would be nice to have a > better > >>> > way to maintain those @since. At least a check of presence, or even > better > >>> > a check of correctness, in the build would nice to have. The must > being to > >>> > have those @since added automagically :) > >>> > > >>> > > >>> >> > >>> >> > > >>> >> > Thanks > >>> >> > -Vincent > >> > >> _______________________________________________ > >> devs mailing list > >> [email protected] > >> http://lists.xwiki.org/mailman/listinfo/devs > > > > > > > > -- > > Thomas Mortagne > > > > -- > Thomas Mortagne > _______________________________________________ > devs mailing list > [email protected] > http://lists.xwiki.org/mailman/listinfo/devs > -- Denis Gervalle SOFTEC sa - CEO _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
