12 Feb
2014
12 Feb
'14
2:33 a.m.
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
<thomas.mortagne(a)xwiki.com>wrote;wrote:
On Tue, Feb 11, 2014 at 3:19 PM, Thomas Mortagne
<thomas.mortagne(a)xwiki.com> wrote:
--
Thomas Mortagne
--
Thomas Mortagne
_______________________________________________
devs mailing list
devs(a)xwiki.org
http://lists.xwiki.org/mailman/listinfo/devs
--
Denis Gervalle
SOFTEC sa - CEO
On Tue, Feb 11, 2014 at 3:15 PM,
vincent(a)massol.net <vincent(a)massol.net>
wrote:
>
> See below.
>
> On 11 Feb 2014 at 13:17:03, Marius Dumitru Florea (
mariusdumitru.florea@xwiki.com(mailto:mariusdumitru.florea@xwiki.com))
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, 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.
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…
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-… 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
>
>
>> > 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