17.3. Version Numbers

Use three-part version numbers.

When specifying the version number of a module, don't use vstrings:

    our $VERSION = v1.0.3;

They will break your code when it's run under older (pre-5.8.1) versions of Perl. They will also break it under newer versions of Perl, as they're deprecated in the 5.9 development branch and will be removed in the 5.10 release.

They're being removed because they're error-prone; in particular, because they're actually just weirdly specified character strings. For example, v1.0.3 is just shorthand for the character string "\x{1}\x{0}\x{3}". So vstrings don't compare correctly under numeric comparison.

Don't use floating-point version numbers, either:

    our $VERSION = 1.000_03;

It's too easy to get them wrong, as the preceding example does: it's equivalent to 1.0.30, not 1.0.3.

Instead, use the version CPAN module and the qv(...) version-object constructor:

    use version; our $VERSION = qv('1.0.3');

The resulting version objects are much more robust. In particular, they compare correctly under either numeric or string comparisons.

Note that, in the previous example, the use version statement and the $VERSION assignment were written on the same line. Loading and using the module in a single line is important, because it's likely that many users of your module will install it using either the ExtUtils::MakeMaker module or the Module::Build module. Each of these modules will attempt to extract and then evaluate the $VERSION assignment line in your module's source code, in order to ascertain the module's version number. But neither of them supports qv'd version numbers directly^[*]. By placing the $VERSION assignment on the same line as the use version, you ensure that when that line is extracted and executed, the qv( ) subroutine is correctly loaded from version.pm.

^[*] At least, not as of the publication of this book. Patches correcting the problem have been submitted for both modules and the issue may have been resolved by nowin which case you should go back to putting each statement on a separate line (as recommended in Chapter 2).

The module also supports the common CPAN practice of marking unstable development releases by appending an underscored alpha count to the version number of the previous stable release:

    

    # This is the 12th alpha built on top of the 1.5 release...
    use version; our $VERSION = qv('1.5_12');

These "alpha versions" will also compare correctly. That is, qv('1.5_12') compares greater than qv('1.5') but less than qv('1.6').