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. 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#@since doesn’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. 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-releases but 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
