Re: [xwiki-devs] [Brainstorming] How to define @since when the package changes?

  See below. On 11 Feb 2014 at 13:17:03, Marius Dumitru Florea (mariusdumitru.florea@xwiki.com(mailto:mariusdumitru.florea@xwiki.com)) wrote: <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.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. 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