11 Feb
2014
11 Feb
'14
3:22 p.m.
On Tue, Feb 11, 2014 at 3:19 PM, Thomas Mortagne
<thomas.mortagne(a)xwiki.com> wrote:
--
Thomas Mortagne
On Tue, Feb 11, 2014 at 3:15 PM, vincent(a)massol.net
<vincent(a)massol.net> wrote:
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.
See below.
On 11 Feb 2014 at 13:17:03, Marius Dumitru Florea
(mariusdumitru.florea@xwiki.com(mailto:mariusdumitru.florea@xwiki.com)) wrote:
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.ht…
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. 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, vincent(a)massol.net
>> 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.
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-… but
the maven plugin doesn't do magic.
-
http://help.eclipse.org/indigo/index.jsp?topic=%2Forg.eclipse.pde.doc.user%…
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
--
Thomas Mortagne > 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
devs(a)xwiki.org
http://lists.xwiki.org/mailman/listinfo/devs