Feature Proposal: Convert to modern perl version strings, and remove subversion artifacts.
For original proposal, See ConvertToModernPerlVersionStrings
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
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
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
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.
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();"
perl -Mversion -e"use version 0.77; print version->parse('1.16230')->normal();"
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.
-- Contributors: GeorgeClark
- 10 Oct 2012
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
- 11 Oct 2012
Seems to be the recommended perl standard. Details in
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.
- 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
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
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.
- 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.
- 13 Oct 2012
Now what's recommended for plugin authors? Do we still need a separate
variable? What exactly is used in
to check for updates:
or both? I am totally confused.
- 25 Oct 2012
continue with the same use. The extensions installer and dependency check code still primarily relies on
and falls back to
. So with this change, it's best to keep them in sync.If you still want to label your releases with alpha strings like
supports, it will continue to work as it did.
If I recall correctly,
was created to permit the
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
string to a real version following the recent perl version guidelines.
we can move away from having both
, but for now the purpose of this change was to only remove the
. I have not touched FastReport
, the extensions installer, or anything else beyond
- 25 Oct 2012
- 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.
- 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
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.
- 13 Nov 2012
A lot of "enterprise" distros ship an old
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
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.
- 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.
- 01 Apr 2014