> > Then now I would put @version 3.0.0, unless the source is (again now) > > totally shared with @version 2.2.0; in the latter case it should be > > 2.2.0. > > There is a lot of shared source. If we were using something like > SourceSafe > instead of CVS, I suggest that quite a few files would be 100% common. In > most cases, any differences are caused by one of a few factors: > > - changes to the Mailet API > - package reshuffling (e.g., moving from james.utils to o.a.mailet) > - interface updates for Avalon > By the way, as an old user of SourceSafe I'm used to share files among projects, and I'm surprised to infer from your words that it is not a common practice (or even not possible) to do it in the CVS world. Is it true?
> This is likely to change as we actually start work on James v3. > > > 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 > > There is no magic, but I agree that the basic idea has been > major.minor.patch, where a major change involves interface changes or > substantial structural change. The minor version is incremented when the > update is more functional than fix. The patch is incremented with each > update to a minor release. > > We've not been using the "rc" designation so far, but that would be a good > idea, especially when bumping anything other than the patch level. > > > "@version 2.2.0" matching the release version means in javadoc > > "*last changed* in version 2.2.0", so we do *not* need to change > > it for no reason when the version changes. > > That is not how the @version tag has been conventionally used, or was > intended. Sun, and the tools vendors, have referred to it as the code > version. Sun's convention is to use the SCCS version > (http://java.sun.com/j2se/javadoc/writingdoccomments/[EMAIL PROTECTED]). > Looking at the use of @version in the JDK, that is what you will see, and > that is how I would suggest using it, e.g., @version CVS $ID$. It doesn't > match against a release version, but it does identify the code version, > which is the real point. The @since tag, on the other hand, refers to a > product version, not a code version. > > So the header could be: > > @version [CVS] $Id$ > @since <release version> > > The use of "CVS" is optional, but would clarify the intention for > anyone who > though that it referred to a release version. > Better then: <P>CVS $Id$</P> @version CVS $Revision$ @since <release version> But, looking at the automatic numbering scheme of CVS (the $Revision$ part of $Id$), I see that it is built on the specific evolution of a source file, and for example two different .java files patched in the same moment for the same reason may have two totally unrelated $Revision$ numbers. And I would like to see a reference to a shared milestone of the project, i.e. the <release version>, in order to understand better the evolution of the source file as it relates to the project. The $Revision$ is instead useful for "logging" and "auditing" reasons. Moreover, I see a relationship between @version and @since (see also http://java.sun.com/j2se/1.4.1/docs/tooldocs/windows/[EMAIL PROTECTED] - it contradicts the link above from this point of view). And also notice that @since (and not @version) can be coded for a method, a constructor and a field, to document the fact that such method etc. has been introduced later on (different from the classe's @since) and may be recent (to better test) or not (distance from the classe's @version and from the current release version). And it is related to the "Specification-Version" and "Implementation-Version" entries of a jar manifest.. It is a completely different usage than a $Id$ of any source control system. So I push ;-) again my first proposal, that IMO would have two (unrelated) advantages: (i) the $Id$ would maintain an automatic reference from the code to the CVS, helping solving potential commit errors and inconsistencies, and (ii) using the <release version> would help understanding the mutual relationhip between different parts: <P>CVS $Id$</P> @version <release version of last change> @since <release version of birth (if possible)> I'm not proposing to make things complicated (if you introduce a complicated convention it will not be followed), but I think that this one is very easy to implement and useful. Waiting again for your comments. Vincenzo --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
