Item1838: Rationalise use of VERSION and RELEASE

Having looked through the code, I see that MTempest coded what looks like some pretty flexible version comparisons. So in theory all that needs to be done is to make that code work on the $RELEASE string, if it is present and recognizable, and only fall back to the $VERSION if it isn't. I'm slightly concerned that the comparison code is too flexible - it allows some pretty dubious constructs, such as "beta" after the version - and it gets hard to describe in simple terms what a valid $RELEASE string actually is. So I propose to cut it down to the following formats:

1. A dd Mmm yyyy format date
2. An ISO yyyy-mm-dd format date
3. A tuple N(.M)+, optionally preceded by 'v'

any text following will be ignored. $RELEASE will be used in the version comparison if, and only if, the format is consistent i.e. DEPENDENCIES and the RELEASE reaped from FastReport have the same format (both are dates or both are tuples), otherwise VERSION will be used. If VERSION is not in the standard format (does not start with a number or $Rev) then it will fall back to a string comparison.

The dd Mmm yyyy date format has to be maintained because it is used all over the place.

In documentation I propose to write the following:

Version number and Release identifier

Two strings are used to identify the version of an extension.

• $RELEASE is a manually-entered string that identifies the "functionality step".
• $VERSION is an automatically generated string that identifies the unique subversion revision that was used to generate the release.

Sometimes extension authors will generate releases from several different $VERSIONs without changing the $RELEASE - when, for example, minor documentation fixes are required that don't justify a complete functionality step.

Foswiki uses these strings in two places; (1) in "Find More Extensions" and (2) when satisfying DEPENDENCIES. For this code to work, the $RELEASE string must:

1. start with one of the following formats: (1) an ISO8601 format date, e.g. 2009-08-07 or (2) a tuple, such as 1.2.3.
2. Be present in the Extension information topic (in the extension info topic) and be consistently formatted with the string in the code.
3. Be consistent with the string used to identify the version in DEPENDENCIES.

If $RELEASE is not available, or the format is not parseable, or used inconsistently, then Foswiki will fall back to using the $VERSION, which must be a subversion revision number. For this to work, the version must be available from the Extension information topic. The easiest way to maintain consistency is to (1) use subversion and BuildContrib (2) stick to the formats recommended and (3) use %$RELEASE% and %$VERSION% in the extension topic.

If you don't use subversion and BuildContrib, you can still use the $RELEASE string, but in this case you must be extremely careful to ensure that it is formatted consistently, and incremented in all the right places when you generate a release.

---

Thanks Crawford for this, but, as I've said already, I still think it's wrong to use Subversion for anything. What you're saying about people not using Subversion, that they have to be extremely cautious when generating a release made me wonder if we couldn't somehow more automate that. That's what I first thought when I wanted to re-design your beautiful BuildContrib (and that's not ironic).

The idea there would be to check on foswiki.org the current version of the extension, and ask the user what they want to do:

1. Bump the patch version number
2. Bump the minor version number
3. Bump the major version number
4. Upload again the same version

The last one, for me, should be highly discouraged. What's the real benefit of not bumping the patch version for a minor doc change? Yes, people won't upgrade for almost nothing, but...

Anyway, you know I have a goal to get rid of this horrid keyword replacement in Subversion, but... it's a long way, and for now, it sometimes does it job.

-- OlivierRaginel - 21 Jul 2009

I think this task has lived its life. Closing it. Current scheme seems to work for the time being.

-- KennethLavrsen - 09 Jan 2010