Beefy Boxes and Bandwidth Generously Provided by pair Networks
Welcome to the Monastery
 
PerlMonks  

What basic things should I know about versioning modules?

by nysus (Priest)
on Feb 23, 2017 at 06:34 UTC ( #1182627=perlquestion: print w/replies, xml ) Need Help??
nysus has asked for the wisdom of the Perl Monks concerning the following question:

I'd like to get some general guidance on how to properly use versioning for my modules.

My question is prompted by the Module::Starter::PBP module. It has a starter template here.

The starter template throws an error on this line: use version; $VERSION = qv('0.0.3');. The error is Global symbol "$VERSION" requires explicit package name (did you forget to declare "my $VERSION"?)

While I could slap a my in front of it and be on my way, I am wondering if maybe it was purposefully left off. I also don't know how this line might be used by other modules. And should I use "my" or "our?" What does qv do? I can't find it in the perldoc but I do find mention of it here on CPAN. But I never installed that module to my knowledge.

If someone could point me to a good resource that can help explain the what's, why's, and how's of module versioning, I'd appreciate it. Thanks.

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

Replies are listed 'Best First'.
Re: What basic things should I know about versioning modules?
by Corion (Pope) on Feb 23, 2017 at 06:38 UTC

    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';

    or

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

    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;

        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;
        is equivalent to:
        BEGIN { require Module; Module->VERSION(12.34) }
        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,
        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.
Re: What basic things should I know about versioning modules?
by haukex (Canon) on Feb 23, 2017 at 07:50 UTC

    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";

    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.

Re: What basic things should I know about versioning modules?
by hippo (Canon) on Feb 23, 2017 at 09:09 UTC
Re: What basic things should I know about versioning modules?
by stevieb (Abbot) on Feb 23, 2017 at 10:23 UTC

    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';

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

Re: What basic things should I know about versioning modules?
by davies (Parson) on Feb 23, 2017 at 07:23 UTC

    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

Re: What basic things should I know about versioning modules?
by RonW (Vicar) on Feb 23, 2017 at 15:14 UTC

    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

Re: What basic things should I know about versioning modules?
by ikegami (Pope) on Sep 19, 2017 at 20:33 UTC

Log In?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: perlquestion [id://1182627]
Approved by marto
Front-paged by davies
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others avoiding work at the Monastery: (5)
As of 2018-09-19 22:13 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?
    Eventually, "covfefe" will come to mean:













    Results (170 votes). Check out past polls.

    Notices?
    • (Sep 10, 2018 at 18:53 UTC) Welcome new users!