You always want the $VERSION variable to be a global variable in your package, because its main use is for other code to inspect it:

use vars '$VERSION';
$VERSION = '1.2.3';
[download]

or

our $VERSION; # since Perl 5.8.x
$VERSION = '4.5.6';
[download]

Using version strings (qv) is not something I would recommend as version strings have been largely recognized as a failed experiment.

What was the version string experiment trying to achieve?

And how, exactly, are these version numbers used by other code? I imagine they are checked to make sure that a module has certain capabilities that it needs. But how does that actually get implemented in practice?

Also, what is the thumb rule for creating new versions? If I fix a typo in a comment, should I increment the version number? I'm guessing no. But when should I?

$PM = "Perl Monk's";
$MCF = "Most Clueless Friar Abbot Bishop Pontiff Deacon Curate";
$nysus = $PM . ' ' . $MCF;
Click here if you love Perl Monks

> how, exactly, are these version numbers used by other code?

They are compared when you say

use Some::Module 6.41;
[download]

See use for documentation, especially

If the VERSION argument is present between Module and LIST, then the use will call the VERSION method in class Module with the given version as an argument:

        use Module 12.34;
[download]

is equivalent to:

        BEGIN { require Module; Module->VERSION(12.34) }
[download]

The default VERSION method, inherited from the UNIVERSAL class, croaks if the given version is larger than the value of the variable $Module::VERSION .

> Also, when is the thumb rule for creating new versions?

See Semantic Versioning for one of the possible strategies.

> If I fix a typo in a comment, should I increment the version number?

Of course. CPAN/PAUSE would reject an upload with an existing version.

($q=q:Sq=~/;[c](.)(.)/;chr(-||-|5+lengthSq)`"S|oS2"`map{chr |+ord
}map{substrSq`S_+|`|}3E|-|`7**2-3:)=~y+S|`+$1,++print+eval$q,q,a,
[download]

Also, when is the thumb rule for creating new versions? If I fix a typo in a comment, should I increment the version number? I'm guessing no. But when should I?

You should definitely increment the version number on every release, as many things will depend on that (CPAN, users of your module that require a specific version, and the general confusion that comes from having two different releases with no good way of keeping them apart). Then, consider whether you need to make a release if all you did is change a code comment.

Things are of course different for modules that are just for internal consumption, in that case the only person the version numbers will have an importance for is you, and you can do things as you like. But since keeping good version numbering is important for any code that goes beyond yourself, it's a good habit to get into.

It wasn't a version string experiment, exactly, but incrementing a version in one module in <bin>/foo/lib over <bin>/lib, to verify that it was using the module that was in the lib-dir of foo. It wasn't intended to remain a different version. Just verifying the older of resolution was what I thought it was.

Unfortunately, I can't find the source at the moment, but I remember reading somewhere that the "best" way to define a package version is simply

our $VERSION = "1.23";
[download]

The reason being that this is the most compatible with the various Perl tools that parse code to find information on modules, and that tricks like parsing the version number out of an SVN tag ("$Revision$") may not work with all of them. I used a string in the above because using a decimal like 1.10 would print as "1.1" instead of "1.10".

See "Version numbering" in perlmodstyle, which advocates version numbers like 1.00, 1.10, 1.11, 1.20 etc. Also, quoting from perlmodlib and Exporter:

To be fully compatible with the Exporter and MakeMaker modules you should store your module's version number in a non-my package variable called $VERSION. This should be a positive floating point number with at least two digits after the decimal (i.e., hundredths, e.g, $VERSION = "0.01"). Don't use a "1.3.2" style version.

Since the UNIVERSAL::VERSION method treats the $VERSION number as a simple numeric value it will regard version 1.10 as lower than 1.9. For this reason it is strongly recommended that you use numbers with at least two decimal places, e.g., 1.09.

There are also lots of other different versioning schemes in use by modules on CPAN. See also CPAN::Version.

I asked a related question a few years ago which prompted some interesting debate (and some which went OT). See Module version numbers best practice for all of that.

Another great question with great responses. Again, I've nothing of substance to add, other than throwing my opinion out there.

I have always, only, ever used the our $VERSION = '1.23'; way of including version numbers. In my distributions that have multiple module, each module file gets the same treatment, and all share the same version number. This means after I do a release to the CPAN, I immediately tag the release, then increment the version number in all the files.

Mostly, I just use '0.01' to begin with, then increment on each release. Once the distribution is in a known sane state where I won't (hopefully) be making any further API changes and I've got a good test suite, I bump the version up to '1.00', and start the process over.

Some of my distributions wrap C libraries, so recently, I've taken to use version numbers that match the C lib, which identifies that "this distribution requires x.xx version of C lib or greater", then I add an extra decimal point after it that identifies the version number of the dist itself, like this:

our $VERSION = '2.36.8';
[download]

So that module requires ABC C library version 2.36+, and the software release is 8 for this track.

I try to use semantic versioning (http://www.semver.org). I believe Puppet uses it, but I don't know about others.

Regards,

John Davies

Note about "1.2.3" style of version numbers.

As haukex points out in Re: What basic things should I know about versioning modules?, that style of version numbering is discouraged.

One practice that some have recommended - and I adopted - is to to zero-pad the "minor" and "patch" parts of the version number and omit the .

Examples: 1.0203 or 1.002003

Caveat: While Perl allows embedding _ within numbers for readability, CPAN uses the _ in a version number to denote that the version is "beta release" and will continue to list the most recent version without a _ as the current stable release.

our $VERSION = 1.002003;  # CPAN stable release

our $VERSION = 1.002_003; # CPAN beta release

To Perl, both will be parsed as the number 1.002003

Oops, this was to be an answer to another question.