Feature Proposal: Convert to modern perl version strings, and remove subversion artifacts.

For original proposal, See ConvertToModernPerlVersionStrings

Motivation

Moving away from SVN. We need to replace the SVN Keywords with something.

Description and Documentation

This is version 2 of the version string proposal. The original proposal had issues with use version 0.77 because of old perl support. We need something that will work without adding CPAN dependencies for perl 5.8.4 or 5.8.8. _The original proposal to use real perl version objects will be reconsidered for the Unicode branch. That branch will require a minimum Perl that supports version directly.

Remove use of $Rev and $Date from $VERSION

• $VERSION will now only support the two accepted perl version formats
  • Dotted triplet: A quoted string, prefixed with "v", major.minor.patch, and optional alpha string
    • $VERSION = 'v1.2.3'; for a normal release
    • $VERSION = 'v1.2.4_001'; for alpha / beta / RC builds.
  • Simple decimal version. Must also be a quoted string, but never includes the "v" prefix:
    • $VERSION = '1.20'; for a normal release
    • $VERSION = '1.21_001'; for alpha / beta / RC builds.
• BuildContrib will be changed to:
  • Detect SVN keywords in the version string and die if present.
  • Detect the last update Date from the repo (no change) and auto-generate a $RELEASE string from the date if $RELEASE is not set.

Automation of Foswiki.pm versions

• The core tools/build.pl will be changed to automate version strings for Foswiki.
  • Prompt for the type of build and automate the VERSION string:
    • major: Start a new Major version. Increments the major version, sets minor and patch to 0, and assigns a _001 alpha suffix.
    • minor: Start a new minor version. Increments the minor version, sets patch to 0, and assigns a _001 alpha suffix.
    • patch: Start a new patch. increment patch, and assigns a _001 alpha suffix.
    • next: Increments the alpha suffix, or if none, increments patch and adds the suffix (same as patch)
    • test (Default): No changes to version strings. Builds as-is with the current VERSION / RELEASE in Foswiki.pm
    • rebuild: Same as test, Used to rebuild the same version, such as after a failed build.
    • release: Building a public release. (not alpha, Beta or RC). Removes the _nnn alpha suffix.
  • Prompt to "Name this release": Used to identify a public release (alpha, Beta or RC). Used as a suffix to the "RELEASE" string
  • $RELEASE is set from the $VERSION, with the addition of the named suffix:
    • VERSION ='v1.1.6_004' "Named as Beta1" will have RELEASE = '1.1.6_004-Beta1'

Automation of Extension versions

TBD

Background for the confused:

The challenge is we are comparing "history". FastReport has to compare the current installed RELEASE and VERSION to the strings stored in Extensions/whateverPlugin. FastReport extracts both the Release: and Version: strings in from the Extensions web. Configure/Dependency.pm then tries to make sense of it. If it can find a RELEASE string, then that is used for the comparison, otherwise it falls back to VERSION.

The "$RELEASE" (or $VERSION if RELEASE is unavailable) is compared to 5 possible layouts (Not necessarily in that order)

# 1. A simple number (subversion revision).
   
# 2 Encoded SVN $Rev$ formats
   
# 3. A dd Mmm yyyy format date
   
# 4. An ISO yyyy-mm-dd format date
   
# 5. A tuple N(.M)+

So I believe that moving VERSION to a PERL version will be initially ignored. The issues will happen if a very old installed ext. still has RELEASE string. But the new version has abandoned RELEASE. This has happened before though, and I think the side effect is just a bit of confusion in the Extensions installer - reporting installed version as older/newer than available version. Once new version is installed, all is happy again.

Examples

Converting to a "proper" version string.

The version module can be used to parse and convert from dotted decimal versions to a v.1.2.3 style triplet: For example, if the SVN Revision for an extension is 16010, it would parse to:

perl -Mversion -e"use version 0.77; print version->parse('1.16010')->normal();"
   v1.160.100
 perl -Mversion -e"use version 0.77; print version->parse('1.16230')->normal();"
   v1.162.300

This isn't required, but is included as a suggestion for manual conversion from a SVN revision to a perl version when no other reference is available.

Impact

WhatDoesItAffect:

%WHATDOESITAFFECT%

edit

Implementation

• <del>Add version.pm to our CPAN lib, and to the DEPENDENCIES</del>
• Foswiki.pm will use a version "v1.2.0"
• Foswiki/Plugins.pm will use version "2.3" (so existing version checks still work)
• Any default extensions with a usable "X.x.x"RELEASE string will be updated to assign a VERSION string as generated by

  use version; print "$RELEASE: " . version->parse($RELEASE)->normal . "\n";

• We should also do this for 1.1.6, so that it is also compatible with a Git repo.

-- Contributors: GeorgeClark - 10 Oct 2012

Discussion

Totally agree with the article; I originally tried to move to a decimal version string back in tmwiki days, but got shouted down by the patch pimps. I'm OK with what you propose ..... but ..... WTF do we need the leading v ?

-- CrawfordCurrie - 11 Oct 2012

Seems to be the recommended perl standard. Details in perldoc version

TYPES OF VERSION OBJECTS

There are two different types of version objects, corresponding to the two different styles of versions in use:

Decimal Versions

The classic floating-point number $VERSION. The advantage to this style is that you don't need to do anything special, just type a number into your source file. Quoting is recommended, as it ensures that trailing zeroes ("1.50") are preserved in any warnings or other output.

Dotted Decimal Versions

The more modern form of version assignment, with 3 (or potentially more) integers separated by decimal points (e.g. v1.2.3). This is the form that Perl itself has used since 5.6.0 was released. The leading 'v' is now strongly recommended for clarity, and will throw a warning in a future release if omitted. A leading 'v' character is required to pass the "is_strict()" test.

-- GeorgeClark - 12 Oct 2012

Still looking at this, if we go with a simple decimal version, then we don't need the leading v, and don't need to use the version code. However that's a much bigger change, for everyone accustomed to the "major.minor.patch" format. So I think staying with the dotted-decimal version would be preferred.

I'm a bit concerned, in that the CPAN module version is standard in 5.10, and needs to be installed on 5.8.8. It appears there are two implementations of version - a pure perl, and an xs version. I installed the pure perl code into our lib/CPAN/lib directory, to avoid any 5.8.8 dependency issues. So far I've been unable to trigger any failures.

One issue with moving to the perl formal VERSION string, is that the %WIKIVERSION% macro is much less descriptive, returning only $VERSION. I figure the solution is to return the $VERSION - $RELEASE strings concatenated instead of modifying VERSION directly as is currently done.

-- GeorgeClark - 12 Oct 2012

Using an official version string removes the descriptive release information. So add a %WIKIRELEASE% macro to expand the release string.

We might want to do something similar with the %PLUGINVERSION% macro.

-- GeorgeClark - 13 Oct 2012

Now what's recommended for plugin authors? Do we still need a separate $RELEASE variable? What exactly is used in configure to check for updates: $VERSION or $RELEASE or both? I am totally confused.

-- MichaelDaum - 25 Oct 2012

$RELEASE and $VERSION continue with the same use. The extensions installer and dependency check code still primarily relies on $RELEASE and falls back to $VERSION. So with this change, it's best to keep them in sync.If you still want to label your releases with alpha strings like $RELEASE supports, it will continue to work as it did.

If I recall correctly, $RELEASE was created to permit the $VERSION to continue to be a subversion rev number, and yet present more human meaningful strings to users.

The only change with this proposal is to convert $VERSION from a SVN Rev and Date which doesn't correspond to a usable perl VERSION string to a real version following the recent perl version guidelines.

Eventually we can move away from having both RELEASE and VERSION, but for now the purpose of this change was to only remove the $Rev$ and $Date$. I have not touched FastReport, Dependency.pm, the extensions installer, or anything else beyond $VERSION.

-- GeorgeClark - 25 Oct 2012

Two issues:

• Configure/UIs/EXTENSIONS.pm compares the "Installed Version" to the string 'HEAD' to detect pseudo-install If the installed version is a real perl version object, then this fails because 'HEAD' is not a valid version.
  • Solution is to use '9999.99_999' as to flag as pseudo-installed. But old Foswiki's still break
  • So old EXTENSIONS.pm need to be patch, or we need a conditional VERSION string in new plugins that avoids creating a version object on old Foswiki.
• BuildContrib still builds a SVN based version string in the Extension topic.

-- GeorgeClark - 05 Nov 2012

Well, this was a lousy idea... or maybe a good idea with lousy timing.

version 0.77 is required to support the parse and declare methods. Released in 2009, people are running into dependency issues due to older versions of version.

Rather than throw this all away, I'm reverting the "use version 0.77; our $VERSION = version->declare" to instead use a simple quoted string that will hopefully be compatible with real version objects once perl in the wild catches up.

Dotted Triplet versions

our $VERSION = 'v1.2.3'; or our $VERSION = 'v1.2.3_001'; for alpha versions.

Simple decimal versions

our $VERSION = '1.140'; or our $VERSION = '1.140_001'; for alpha versions

Always quote decimal version strings. otherwise trailing zeros will be lost. '1.14' vs. '1.140' And to be forward compatible with future perl version objects, always include the v prefix on dotted triplet versions.

To convert from a decimal version to a dotted version, first normalize the decimal version, then increment it.

perl -Mversion -e 'print version->parse("4.44")->normal'  ==>  v4.440.0

In this example the next version would be v4.441.0.

-- GeorgeClark - 13 Nov 2012

A lot of "enterprise" distros ship an old version.pm incompatible with the newly recommended way of declaring a version. This breaks updating extensions for a lot of users. I am going to revert the use version yadda from all of the extensions I maintain and revert them to a plain string holding a float. This seems to be the simplest way to (a) write a plugin (b) compare version numbers and (c) maintain backwards compatibility with ancient perls.

See Tasks.Item12583.

-- MichaelDaum - 12 Sep 2013

I think we can set this to accepted, but the recommended practise is to use simple decimal versions in extensions so they can be installed anywhere. Core can continue to use the vx.y.z style since we don't actually test that anywhere. The issues come during extension version checks.

If an extension chooses to use the vx.y.z format, they still need to "use version", and everything should continue to work if perl is reasonably curent.

-- GeorgeClark - 01 Apr 2014

Commenting is disabled while not logged in