Javadoc @version, @since and CVS $Id$

[Vincenzo Gianferrari Pini <vi...@praxis.it>]

Partially following a suggestion from Danny (http://archives.apache.org/eyebrowse/ReadMsg?listName=james-dev@jakarta.apache.org&msgNo=8773), in the patches I recently submitted I've started to code the following at the end of the javadoc comment for a class:

 *
 * <P>CVS $Id$</P>
 * @version <james current building version>
 * @since <james initial building version>
 */

The $Id$ string will be substituted by CVS with useful change control information, while @version and @since have a James "release" related meaning.

For instance, these days we are dealing with James 2.2.0a5, so in AbstractRedirect I coded 2.2.0 for @version and for @since; the outcome was:

 *
 * <P>CVS $Id: AbstractRedirect.java,v 1.1.2.9 2003/06/15 18:40:20 noel Exp $</P>
 * @version 2.2.0
 * @since 2.2.0
 */

Obviously the @since entry can be inserted into new classes only.

It becomes necessary to have someone decide and announce, when a new release comes out, the number of the next release: when finally releasing 2.2.0, we should know the next one.

What should be done for *v3* modules? If there is (I don't know, sorry) a currently mantained numbering scheme, we could use it, otherwise it could be used the v2 numbering until v3 is under development only.

I think that all this could be a convention that everyone could follow, because IMHO it is useful for understanding the evolution of the code, and very simple to implement: just a "copy and paste".  What do you think? Is there a better way of doing it? Is it worth?

Vincenzo


---------------------------------------------------------------------
To unsubscribe, e-mail: james-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: james-dev-help@jakarta.apache.org

RE: Javadoc @version, @since and CVS $Id$

[Danny Angus <da...@apache.org>]

> If there is (I don't know, 
> sorry) a currently mantained numbering scheme, we could use it, 
> otherwise it could be used the v2 numbering until v3 is under 
> development only.

There is a numbering scheme, best let Noel of Serge explain it.. my understanding is is..
current HEAD is v3, working towards release v3.0, first alpha will be 3.0a1, first release candidate will be 3.0rc1
first released version will be 3.0.0

Current stable is v2, currently v2.2, first alpha would be 2.2a1 first release candidate 2.2rc1
Small fixes, eg bugfix, might be released as 2.2.1, larger changes would result in 2.3


> I think that all this could be a convention that everyone could 
> follow, because IMHO it is useful for understanding the evolution 
> of the code, and very simple to implement: just a "copy and 
> paste".  What do you think? Is there a better way of doing it? Is 
> it worth?

I'm not sure that "@version 2.2.0" matching the release version makes much sense, because it means we'd have to change it for no reason when the version changes.

Otherwise I think its a reasonable idea.

d.

> 
> Vincenzo
> 
> 
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: james-dev-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: james-dev-help@jakarta.apache.org
>