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#@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 -- Thomas Mortagne _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
