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 <[email protected]> wrote: > On Sun, Feb 9, 2014 at 11:16 PM, Thomas Mortagne > <[email protected]>wrote: > >> On Sun, Feb 9, 2014 at 6:10 PM, [email protected] <[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. > > 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 >> > > > > -- > Denis Gervalle > SOFTEC sa - CEO > _______________________________________________ > devs mailing list > [email protected] > http://lists.xwiki.org/mailman/listinfo/devs _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
