xml-general mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Mike Pogue <mpo...@apache.org>
Subject Re: Proposed guidelines for package distribution of Java projects
Date Mon, 22 Nov 1999 16:41:50 GMT
Note that Xerces-J and Xerces-C both already have a mechanism for
versioning.
I agree that this is important (it's why this stuff is in there
already!).
I would like to see a project-wide way of doing this.  It is a pain in
the butt,
however, to maintain.

On the J side, check out:

	Version.java

On the C side, check out:

	XML4CDefs.hpp (I know -- we missed this.  The name will change to 
		XercesDefs.h, or something similar).

Over time, here's what we learned about version numbering:

1) The information should be strings.  Do NOT count on it being a
floating point
	number with a single dot (as some have done in the past).  This
assumption causes
	many things to break.

2) It is important to establish a version numbering scheme that lets
people know (to a 
	first approximation) when binary compatibility is maintained (third
number 
	changes), and when it is not (second or first numbers change).

3) We have needed three numbers, plus a "in development/unstable" and a
"stable/frozen" 	designation.  We've used EA (Early Access) and D
(Development) for this fourth 
	designation.  Both have	worked.  We use "Reference Release" for the
stable/frozen
	designation.  So, this is what it looks like, and it's worked for us:

		version 1.2.0 EA1 (or D01)	= development version, unstable,
							probably not feature complete,
							use at your own risk
		version 1.2.0 EA2 (or D02)	= another development version, unstable,
							probably not feature complete,
							use at your own risk

		version 1.2.0			= first relatively usable version
		version 1.2.1			= minor delta, still compatible, probably 
							bug fixes

		version 1.3.0			= API or semantic change
		version 1.3.1			= minor delta again, no API change
		.
		.
		version 1.4.15	REFERENCE	= Reference Release designation means
							very stable, API frozen, severity
							1 (critical) bug fixes only

		version 2.0.0			= major API change, or rewrite, or 
							continuation of development following
							a reference release (API allowed
							to change again)

4) Version number discussions take an infinite amount of time.  Every 6
months, somebody
	will want to change it because it's not right for *them*.  Don't be
surprised when
	this happens.  Once you've converged on a numbering scheme, don't get
sucked into
	it again and again.  
	It's worse to change the numbering scheme, than it is to live with
	the limitations of the current one.  Changes just create massive
confusion.
	Note that long version number discussions take brain power away from
feature adds.

5) It's hard to remember to do it every build.  Force the build script
to do as much
	as possible, e.g. automatically change the files where needed, to the
correct
	version number. 

6) Don't forget that version numbers are in the documentation, too.

Hope this helps!
Mike


James Tauber wrote:
> 
> > We should be explicit about whether we intend this version label to
> > be usable in strict numeric comparisons, meaning that there is just
> > one decimal point.
> 
> If you plan the number of digits, you can have three or more revision levels
> and do a lexical comparison.
> 
> eg   00.05.02
> 
> I definitely prefer three-field versions. With FOP, I've increased the least
> significant for bug-fixes and minor code-cleanups, the middle field for new
> features and major code changes. I haven't increased the most-significant
> field because I'm saving that for when the spec is finished.
> 
> > This raises some interesting possibilities in the build/make area.
> > Can we put the name and version labels in exactly one place in the
> > source, then generate the package name from them?
> 
> I would like that very much.
> 
> James

Mime
View raw message