http://www.perlmonks.org?node_id=780275

ig has asked for the wisdom of the Perl Monks concerning the following question:

I would like to know current recommendations and the advantages and disadvantages of the various module version numbering schemes.

I have read version, problem incrementing module version number, module version convention, Re: Versioning modules in a package, Can't use three part version number for CPAN modules, Seeking thoughts on version numbers in modules and various other discussions.

The version documentation has some best practice guidance and suggests that extended versions will become preferred with Perl 5.10.0, but looking at the core modules in current blead suggests otherwise and that version is not preferred.

Most of the core modules and module templates created by Module::Starter have $VERSION set similarly to the following:

our $VERSION = '1.17';

[download]

For new modules:

About the only thing that seems reasonably certain is that I shouldn't use v-strings.

update: UNIVERSAL::VERSION, by default, compares versions when a module version is specified in a use statement. But it's documentation doesn't say much about how it does comparison. The version modules replaced UNIVERSAL::VERSION, presumably to provide different behavior. It would be good to know what is compatible with the various (at least the common) implementations, across different versions of perl and version at least, and any other modules that replace UNIVERSAL::VERSION.

update: John Peacock is evolving the version.pm module for the upcoming perl 5.10.1 release. David Golden has updated (work in progress) documentation for the upcoming release, there is an (older) annotated copy of the version POD with some helpful comments and there is some relevant discussion on P5P list. I guess this is as current information as one can hope to find and from a group that is as in-the-know as one could hope.

update: See also A modest proposal on P5P, started by John Peacock.

update: http://www.dagolden.com/index.php/369/version-numbers-should-be-boring/

Replies are listed 'Best First'.
Re: module version numbers
by JavaFan (Canon) on Jul 15, 2009 at 13:18 UTC
    I think if the only goal is to reduce misinterpretations or incompatabilities, you should use version numbers without digits. Just counting from 1 (or 0) will do. Some people use YYYYMMDDhhmm. DNS uses YYYYMMDDXX, with XX starting at 01 and incrementing to 99 for updates happening the same day.

    The reason is that Perl considers '1.2' a newer version than '1.19' - '1.2' being a shorthand for '1.200', and '1.19' a shorthand for '1.190'. And that's fine when all you have to care about is Perl and its common infrastructure. But if you interact with tools or people that aren't focussed on Perl, you may encounter tools or people who consider '1.2' an older version than '1.19'.

    I'm not claiming one system is better than the other. (Although considering '1.2' newer than '1.19', but '1.19.0' to be newer than '1.2.0' is something I find confusing). Just that eliminating dots has its benefits.

    Of course, that way you lose the convention that the more dots after the incremented number changes, the bigger the change is. But I've seen small projects using version numbers like 1.2.3.4 which makes me wonder what kind of change bumps the version to 1.2.3.5 and what kind of change bumps it to 1.2.4.0. Or 1.3.0.0.

[reply]

      I assume you mean numbers without dots rather than without digits.

      I like the DNS convention and have used it elsewhere, but would miss the major/minor distinction for a module. I may not be good at it, but I like the idea of the major version number changing as the committed interface changes, or when incompatibilities are introduced. An API version number could be added as a prefix, maybe with an underbar for visual distinction. Perhaps something like: 'MM_YYYYMMDDXX'

      Yet, floating point numbers with only a couple of digits after the decimal point seems to be the most common, among the few modules I have looked at. I'm more of a sheep than a wolf, nervous about doing something unconventional which may become an unfortunate edge case some day.

      As an alternative to multiple dots in the extended version numbers, I have the impression that there is some special handling to preserve an underbar in the fractional part of a floating point version (e.g. "1.02_03"), but maybe this is only in version, and I don't understand why the example isn't "1.002_003".

      Not that I'm pinning any of this on you - I appreciate your comments.

[reply]
Re: module version numbers
by syphilis (Archbishop) on Jul 15, 2009 at 12:47 UTC
    About the only thing that seems reasonably certain is that I shouldn't use v-strings

    Why is that ?
    I think some of my modules *do* use v-strings. At least I find I have (in some of my modules) things like: 
    $My::Module::VERSION = '1.23';

    [download]
    Others of my modules don't stringify the version: 
    $My::Other::Module::VERSION = 2.45;

    [download]
    I've always simply specified my versions as x.xx and have had no problems with that (irrespective of whether the x.xx is stringified or not). I guess this might impose some limitations on my options but, as far as I'm aware, it doesn't impose any limitations that bother me.

    I now begin to wonder if I'm doing something that *should* concern me :-)

    Cheers,
    Rob
[reply]
[d/l]
[select]
      Why is that ?

      The version documentation has a section on v-strings that begins:

      Beginning with Perl 5.6.0, an alternate method to code arbitrary strings of bytes was introduced, called v-strings. They were intended to be an easy way to enter, for example, Unicode strings (which contain two bytes per character). Some programs have used them to encode printer control characters (e.g. CRLF). They were also intended to be used for $VERSION, but their use as such has been problematic from the start.

      And goes on to more discouraging things, including:

      the use of bare v-strings to initialize version objects is strongly discouraged in all circumstances (especially the leading 'v' style), since the meaning will change depending on which Perl you are running.

      Then gives some guidance in case you insist on using bare v-strings with Perl > 5.6.0.

      Re-reading this now, maybe it is only bare v-strings that are being discouraged. On the other hand, maybe they are all problematic but only the bare ones are being strongly discouraged.

      Otherwise, Why will v-strings be deprecated and v-strings deprecated; what to use instead? suggest v-strings are deprecated. Have they since been redeemed?

      v-strings must die! also suggests v-strings are not good. But this is from 2003, so the situation and intent could have changed since then.

      Maybe I shouldn't have been so quick to scratch v-strings off my list of possibilities?

[reply]
[reply]

      I don't think versions like:

      $My::Module::VERSION = '1.23';

      [download]

      are the deprecated v-strings, despite being strings with version numbers in them. If you put a 'v' at the front, then it might be a v-string and I am more certain that if it was unquoted with a v in front that it would be a bare v-string. So, if I understand correctly, many people consider the following to be bad:

      $My::Module::VERSION = v1.23;

      [download]

      On the other hand, see Re: Seeking thoughts on version numbers in modules - maybe v-strings (the magic variety as of 5.8.1) are OK after all. Still, my conclusion is that with so much contention, it is probably safer to use some other form (like what you are using, which is consistent with most of the core modules), at least until the dust settles on v-strings, one way or the other.

[reply]
[d/l]
[select]
        Excellent ... nothing for me to worry about :-)
        Thanks for clarifying.

        Cheers,
        Rob
[reply]

      I think some of my modules *do* use v-strings. At least I find I have (in some of my modules) things like:

      Those aren't v-strings. v-strings start with a literal "v" like v1.2 and v1.2.3. Use version's qv instead of using v-strings.

[reply]
[d/l]
[select]
Re: module version numbers
by DStaal (Chaplain) on Jul 15, 2009 at 12:50 UTC

    version looks nice... If you are targeting Perl 5.9 or greater. 5.8 is still very common in the wild, which may be a reason many module authors avoid it. (It's why I do.) Of course, you can list version as a dependency, but that adds another step to the install and complicates things for the user.

    I personally use the numeric X.YYZZ format, meaning version X.YY.ZZ, as the most compatible format at the moment. (And I let ModuleMaker set it up in a BEGIN block, as that's easy.)

    Really, it comes down to: Pick whatever you feel comfortable with that doesn't cause problems for your users. v-strings cause problems. version is a minor annoyance for anything earlier than 5.9. Numeric seems to cause me the least amount of headaches, but that's me.

[reply]

      Does X.YYZZ translate to version X.YY.ZZ or X.YYZ.Z00? I thought the translation from numeric to extended version strings took three digits after the decimal point for the second and third version numbers (midor and minor I think I have seen them called).

[reply]

Back to Seekers of Perl Wisdom