Beefy Boxes and Bandwidth Generously Provided by pair Networks
Problems? Is your data what you think it is?
 
PerlMonks  

Seeking thoughts on version numbers in modules

by xdg (Monsignor)
on Dec 27, 2004 at 16:53 UTC ( #417576=perlquestion: print w/ replies, xml ) Need Help??
xdg has asked for the wisdom of the Perl Monks concerning the following question:

I'm looking for some recommendations on best-practices for version numbers in modules. There's several different "standard" approaches out there, but there doesn't seem to be a lot of consensus in actual pracice. I'm still not sure if we're supposed to be using v-strings or not, or "our" vs "use vars" for that matter, and I've other questions, too. After playing with version number parsing in response to Help update the Phalanx 100, it's clear that TIMTOWTDI rules on CPAN with distributions numbered all sorts of strange ways. I'd like to spark some discussion on the topic and see what people's latest thoughts are. Background reading for this discussion could include Everything you wanted to know about Module Version Numbers and Checking and the version module, the VERSION_FROM section of ExtUtils::MakeMaker, and Other Conventions from PAUSE.

Here are some questions (in no particular order):

  1. What is the current status of v-strings? Should they be used? If so, how? Should we be using version to provide backward compatibility? (version requires only perl 5.005_03.)
  2. "our" or "use vars"? How important is compatibility to perl prior to 5.6? (How much perl 5.005 is still in use in the wild?)
  3. Is there consensus on the best way to number versions? major.minor.release? How should major.minor.release compare to major.minor_release (i.e. an "alpha" release? (verson treats 1.3.0 < 1.3_1 < 1.3.1) I'd assume that forms like "1.2b" and "1.2_pre3" should not be used?
  4. How are people integrating version numbering with their source control systems? CVS approaches are plentiful. How are people handling this for subversion or other systems that maintain global repository revision numbers?
  5. What is a good way to synchronize version numbers across several .pm files in a distribution? Separate version numbers in each file updated by hand (or with a perl one-liner)? What about having each package require a "master" .pm and using its version number? Other approaches?
  6. What is the best way to prepare for forward compatibility with perl 5.10 or perl6?
  7. What do PAUSE and CPAN use internally to parse version numbers?
  8. What other things about module versioning do you wish you knew?

I'd love to hear answers to any/all of these questions or to see additional questions on the same topic.

Thanks very much

-xdg

Code posted by xdg on PerlMonks is public domain. It has no warranties, express or implied. Posted code may not have been tested. Use at your own risk.

Update: Several people have commented that v-strings are deprecated, but I'm not sure this is entirely true. From what I can see, the "version" object is going into the core, and its documentation suggests that only the leading-v form "v10.2" is being deprecated, whereas bare numbers with two or more decimal places will continue to be treated as v-strings. The documentation for version as included in perl-5.9.1 certainly has a lot to say (almost too much) on the topic. (AM's comment about his/her brain popping is apropos.) Can anyone involved in perl 5.9/5.10/perl6 shed some light on the direction of v-strings?

Update 2: After reading comments here, reading version several times, and researching mailing lists and even code for Module::Build and ExtUtils::MakeMaker, I've come to the personal conclusion that version is headed in the right direction, but won't be appropriate for widespread usage until it has better support within Module::Build and ExtUtils::MakeMaker. See this thread and this post in particular.

Comment on Seeking thoughts on version numbers in modules
Download Code
Re: Seeking thoughts on version numbers in modules
by dragonchild (Archbishop) on Dec 27, 2004 at 17:01 UTC
    1. No idea.
    2. "use vars". 5.005 is in heavy use. Think financial systems - Wall Street is one of the largest Perl consumers as an industry. I know at least one major bank that uses Perl to do nearly all their back-end batch processing. Banks don't like change; if 5.005 processed yesterday's transactions, it'll do for tomorrow's transactions.
    3. I label mine major.minor. I start the numbering at 0.01 and go up every release. I don't deal with the major.minor_release or anything like that. Developer releases seem like too much trouble to me.
    4. I don't bother integrating with Subversion (I use svn.perl.org). I'm tag-it-and-bag-it kind of hacker. So, I have a tag for each release to CPAN.
    5. I have a version number in one file in each distro. The other files don't need them, AFAIK. And, using Subversion, I don't need revision numbers in the other file because SVN does revision control for the project, not each file like CVS.
    6. What problems do you anticipate with 5.10, Ponie, or Perl6?
    7. Don't know.
    8. What's the ANSI standard and do we care?

    Being right, does not endow the right to be rude; politeness costs nothing.
    Being unknowing, is not the same as being stupid.
    Expressing a contrary opinion, whether to the individual or the group, is more often a sign of deeper thought than of cantankerous belligerence.
    Do not mistake your goals as the only goals; your opinion as the only opinion; your confidence as correctness. Saying you know better is not the same as explaining you know better.

      Great comments. #5 is intriguing and I poked around a little to investigate. It looks like CPAN (er., search.cpan.org anyway) maintains version numbers on all files, but only if they exist. And the version of individual files can bear little/no relation to the distribution version. Compare these:

      I wonder if the version number for the distribution that CPAN uses even comes from a file at all or simply from the distribution tar file numbering (or a META.yaml file, if it exists). If the latter is true, you could manually set your version in a Makefile.PL or Build.PL and have no VERSION in your files at all.

      The only downside I see to this (and to leaving version numbers out of submodules) is that you lose version checking ability. If a distribution contains a "main" module and submodules that would never be directly used, then it won't really matter if you only have a VERSION in your main module file. On the other hand, if a distribution contained modules which could be used independently, then it does matter.

      See Test-Simple for an example where this might be the case. (It's not, for reasons I'll explain, but bear with as an example.) Test::Builder's version is out of sync at 0.22 compared to 0.54 for distribution as a whole. In a Makefile.PL or Build.PL, if my list of pre-requisites had Test::Builder => 0.22, and Test::Builder's version number hadn't been updated in a while, I could pass the pre-req with an old version of Test::Builder, even though the distribution version number of the Test-Simple distribution had been updated. It turns out in this case, that Michael does actually increment Test::Builder's number when it changes, but only when it changes and not just because Test::More or Test::Simple or the distribution version number change.

      This may suggest a general good practice of using the same module in a prerequisites statement as is being used to generate the version number for the distribution, just in case the distribution author isn't as diligent about maintaining all the version numbers.

      -xdg

      Code posted by xdg on PerlMonks is public domain. It has no warranties, express or implied. Posted code may not have been tested. Use at your own risk.

        It's funny you mention Excel::Template because I'm the author. I actually deliberately removed version numbers from the individual files because I wanted to have a version number for the release. The individual files don't matter as much as the functionality from the release itself.

        I wonder if the version number for the distribution that CPAN even comes from a file at all or simply from the distribution tar file numbering (or a META.yaml file, if it exists).

        In your Makefile.PL (or Build.PL, I suppose), there is an item called VERSION_FROM or VERSION. If you have a VERSION, CPAN uses that. If you have a VERSION_FROM, CPAN goes into that file and looks for the first $VERSION line. (It's a little more complicated than that, but you get the idea.) This is all documented in ExtUtils::MakeMaker (and, I'm sure, in Module::Build).

        Being right, does not endow the right to be rude; politeness costs nothing.
        Being unknowing, is not the same as being stupid.
        Expressing a contrary opinion, whether to the individual or the group, is more often a sign of deeper thought than of cantankerous belligerence.
        Do not mistake your goals as the only goals; your opinion as the only opinion; your confidence as correctness. Saying you know better is not the same as explaining you know better.

Re: Seeking thoughts on version numbers in modules
by gaal (Parson) on Dec 27, 2004 at 17:11 UTC
    My incomplete take on this:
    1. v-strings are deprecated (see perldelta).
    2. How are you using the new features of Perl 5.6 and on? If $VERSION is the *only* place you're using new syntax, it would be obtuse to exclude users of old perls, but any other case can certainly be argued either way. (Anyone remember when for became a statement modifier? IIRC this wasn't in 5.000.)
    3. I don't think there's a concensus on version number format. I'd recommend perl-like version numbers.
    4. I'm of the opinion that source control versions and release versions are completely different. The former is meant for the developer. It's fine to include an $Id$ in your files, but the package itself should have a public version number that is updated much less frequently.
    5. I use a single $MyProject::Common::VERSION value and instruct everything to look there.
Re: Seeking thoughts on version numbers in modules
by Anonymous Monk on Dec 27, 2004 at 17:14 UTC
    1. IMO, v-strings should die. And I think they will. Many people consider them one of the many experiments that failed. Someone on p5p is working on "version" objects, intended to be used where v-strings should be used for. But each time I try to understand what they are supposed to do, and how it orders version numbers, my brain pops.
    2. If your module is supposed to work for Perls older than 5.6.0, there's no option to use our. How important compatability is is something you have to work out for yourself. Who's your target? And consider how it feels if you can't run software because you don't have the newests and greatest version of your OS/libraries/distro/browser/Perl/compiler/whatever. IMO, you don't have to support old versions for ever. But to break compatibility just so you can write our instead of use vars isn't very friendly either.
    3. There is absolutely no concensus on how to label your versions. There isn't even concensus on whether 1.10 is newer than 1.9. (Perl itself, and by extension CPAN, don't think so. Commonly used version control systems like CVS do).
    4. That's common. But be aware of my previous point. Blindly taking CVS's versions numbers will cause the CPAN indexer to do thinks you don't expect. A way of using CVS to generate version number is to have the string '$Revision: $' in your program, followed by a regex to extract the version number, with the result assigned to $VERSION. All on one line to please MakeMaker.
    5. Never thought about that. IMO, not necessary either. The CPAN indexer doesn't have a problem with version numbers not all equal.
    6. Considering noone know who perl5.10 or perl6 will look like (the latter changes every week), the question is impossible to answer. I don't know if there's even a way to prepare for 5.10 and 6, let alone "the best" way.
    7. No idea.
    8. I wished that every one used dotted integers as version numbers (just like CVS does). No underscores, letters, and certainly not "floating point" numbers with more than one period (like Perl does).
Re: Seeking thoughts on version numbers in modules
by revdiablo (Prior) on Dec 27, 2004 at 17:55 UTC

    I am not going to individually answer each question you've asked, as it seems there are already some pretty good answers. I would just like to explain the versioning scheme I use. Basically, I'm copying OpenBSD's scheme, except I don't release on a regular cycle. I think that's a good idea, but I don't make enough changes to justify that type of thing.

    I start a project at 0.1, and for every release (e.g. every time I upload to CPAN, every time I make a .tar.gz for someone) I increment the minor number. If it's at .9, then I increment the major number. So 1.0 always follows 0.9.

    I don't assign any special meaning to the major number; it's simply a function of how many releases I've made. I also don't have special stable/unstable branches. I can understand the reasoning behind these things, but I'm just not sure the extra complexity is worth it for the projects I work on.

    Update: sorry for just updating the node, but my reply doesn't quite deserve a whole new node. gaal said:

    You may as well use integers, no?

    Yes, but I like X.Y version numbers. They make me feel warm and fuzzy.

      You have a "build number", which is a perfectly legitimate scheme for versioning, only the units are 0.1.

      You may as well use integers, no?

•Re: Seeking thoughts on version numbers in modules
by merlyn (Sage) on Dec 27, 2004 at 18:47 UTC
Re: Seeking thoughts on version numbers in modules
by tye (Cardinal) on Dec 27, 2004 at 18:56 UTC

    1.3.1 isn't going to fly since v-strings are deprecated. I number modules as j.nn_ww: j=maJor revision, something that probably involves non-trivial interface changes; nn=miNor revision, which should include a batch of bug fixes and/or feature enhancements; ww=Whatever, which I increment for any trivial reason such as when I copy the module somewhere to test on a new platform or even after I've made trivial changes but have stopped working on it for a while even though I don't plan on making a release any time soon.

    Update: Note that with this scheme I have mostly abandoned the idea of having "pretty" version numbers. I once strived to have version 1.02 follow version 1.01 and have the first really stable version of the module be version 1.00 or 1.01 (and have beta versions marked with a "b" or some other convention) etc. But I've come to decide that "pretty" just ain't worth much.

    Version numbers should be simple and sort easily. And if two copies of a module are different then they really need to have different version numbers. So a big point is that the version number needs to increment at the drop of a hat, that is, whenever the module gets copied anywhere, even if (I think) I'm the only one who will ever see that copy.

    A lesser point is that I've never been blessed with a community of module users that I would call a crack module testing team. So I never reach some point where I declare a module "out of beta". I release modules when I have something to release. If no bugs reports or requests come in, then I'm not going to make a new release with an announcement of "I haven't heard any complaints so I'm changing the version number and it is no longer beta". I'm sure such would just lead to needing a new release almost immediately. (:

    Note that I also avoid trailing zeros in version numbers so there is no 1.19_00 and after 1.19_09 is 1.19_11.

    - tye        

Re: Seeking thoughts on version numbers in modules
by petdance (Parson) on Dec 28, 2004 at 04:51 UTC
    My version numbers are always x.yz or x.yz_ab. If yz is even, then it's a release version. If yz is odd, then there will be a _ab that goes up starting at _01 for each beta release.

    So you get 2.42, 2.44, 2.45_01, 2.45_02, 2.45_03, 2.46.

    xoxo,
    Andy

Re: Seeking thoughts on version numbers in modules
by jonadab (Parson) on Dec 28, 2004 at 05:13 UTC
    I have just one comment about version numbers: use leading zeros on the minor number from the get-go, so that you don't end up with the awkward situation of leaving people wondering whether 0.13 comes before 0.2 or quite a bit after it. If you start with 0.01, 0.02, and so forth, you have until 0.99 before you need to increment the major number just to avoid ambiguity. If you use three numbers, start with 0.01.01 or similar, for the same reason.
What's with the 0.1 initial release?
by Anonymous Monk on Dec 28, 2004 at 09:56 UTC
    I've always wondered why so many people start with a '0.1' or a '0.01' release. I know it's cool to show you know that computers start counting with 0, but then, shouldn't you start counting at '0.0'?

    I usually start with 1.1 (for anything non-Perl, or anything that isn't going to CPAN), and 1.100 or 1.1000 for anything that's going to CPAN. I always try to have my source control system take care of generating the version numbers for me. (It tends to make less mistakes than I do, and why do something by hand if you can automate it? It's more fun to spend an hour or two to figure out how to have the version control system generate the numbers for you than to do 5 seconds of manual work with each release ;-))

      I've always wondered why so many people start with a '0.1' or a '0.01' release.

      Traditionally, a 0.x version number indicates an early release, an unfinished beta. Once the project becomes stable, it is usually upgraded to 1.x.

Re: Seeking thoughts on version numbers in modules
by blazar (Canon) on Dec 28, 2004 at 12:37 UTC
    Update:Several people have commented that v-strings are deprecated, but I'm not sure this is entirely true. From what I can see, the "version" object is going into the core, and its documentation suggests that only the leading-v form "v10.2" is being deprecated, whereas bare numbers with two or more decimal places will continue to be treated as v-strings. The documentation for version as included in perl-5.9.1 certainly has a lot to say (almost too much) on the topic. (AM's comment about his/her brain popping is apropos.) Can anyone involved in perl 5.9/5.10/perl6 shed some light on the direction of v-strings?
    I'm not sure if this will shed any light, but Perl6 will definitely support v-strings. Incidentally I'm one of those who things that even if it may have been an error to introduce them in the first place, it will be an even worse one to remove them altogether; also because with the new autoquoting rules risk of confusion IMHO has been reduced considerably. However you may be interested to read what Larry Wall wrote to me in answer to a related inquiry:
    : Incidentally, and on a totally OT basis, I've noticed that Perl6 is
    : supposed to have v-strings. But (current) 'perldoc perldata' warns that
    : they won't be there after 5.8: taking all this into account I wonder
    : wether this would be a wyse choice. I mean: maybe it hasn't been such a
    : good thing to introduce them in the first place, but now that they're
    : there, it may be even worse to remove them...
    
    The problem wasn't the syntax so much as the semantics.  In Perl 6,
    C<v6> creates a string, not an object, so there's no way to overload
    its operators to avoid conflicts with other kinds of strings.
    In Perl 6 C<v6> makes a version object, not a utf-8 string, and
    they compare using numeric operators instead of string operators.
    (Perl 5's v-strings had a numeric component that was an old-style
    floating point number version (5.00401, for instance), and you could
    compare those numerically.  Perl 6 will be able to handle those via
    MMD without compromising the normal comparison semantics when you
    compare two version objects with numeric comparisions.)
    
Re: Seeking thoughts on version numbers in modules
by drfrog (Deacon) on Dec 29, 2004 at 01:49 UTC
Re: Seeking thoughts on version numbers in modules
by JPeacock (Novice) on Jan 26, 2005 at 20:07 UTC
    Being sort of the resident $VERSION guru (and, no, this isn't a good thing), I'll take a crack at these.

    Here are some answers (all IMNSHO unless otherwise noted):

    1. v-strings are not deprecated, as such. See the discussion below for details.
    2. If you want to use 'our' make sure that you also 'require 5.6.0;' at the same time. 'use vars' always works, but if you have no need to support earlier Perl's, there is no reason not to use 'our'
    3. One thing to realize is that because version.pm has to follow the Perl versioning rules (as set out in the 5.6.0 release), subversions are 3 decimal places and not 2, so 1.23_04 is displayed by version.pm as 1.230.400 (when stringified).
    4. I'm using Subversion myself and I don't have a good answer yet; I have been working on a custom keywords patch which would permit setting a property which would populate the $VERSION string. I have pseudocode for a script called 'release' which would increment the property, build and test the distro, check it into the repository and create a release tag. No, it's not done yet. ;)
    5. If the modules will never live an independent life, share the $VERSION with the master module; if not, $VERSION scalars are cheap and it would be easy to create a script which will check to see if a given PM file has changed and increment the $VERSION. Yes, I have some ideas for version::Math...
    6. The code that constitutes version.pm exists in bleadperl and is very likely to remain there for 5.10.0. If you want to make sure that your module works, you can 'use version;' which will be a no-op in 5.10.0 and will load the compatibility layer back to 5.005_03. Think of version.pm as a pragma (which it is) that changes the version handling to correspond to the future of Perl.

      The v-string dilemma

      There are sadly too many evil^Wuseful ways that people have used them to permit their wholesale destruction. However, the use of v-strings as $VERSION is not recommended except in Perl 5.8.1 or better. The short story is that until the magic v-strings were introduced with 5.8.1, it is impossible to tell whether a given scalar was originally created via a v-string (i.e. it is a lossy transform in the tokenizing phase).

      However, Larry has indicated that the leading 'v' numbers will be used in Perl6 to be version objects (which may or may not be implemented in the same way as version.pm and 5.10.0 does). So I think that by the time Perl6 is out, the use of code like this will be eliminated:

      my $crlf = v13.10;

      Yes, that is actual code in the wild!

      Other version magic

      Someone asked about a way to be very specific about what versions of a module could be used, so I created version::Limit to specify exactly which releases were compatible. If you value a strong API, it may be useful to you. NOTE: that this module is most useful with Perl 5.8.1 or better, so you can use bare v-strings and have it mean what you think it means.

      If you want to use arbitrary version strings, like 1.2b2, and still have them sort like you would like them to, you might find version::AlphaBeta useful; then again, you might be insane. ;)

      I hope this helps more than it confuses things.

      John Peacock

Log In?
Username:
Password:

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

How do I use this? | Other CB clients
Other Users?
Others browsing the Monastery: (4)
As of 2014-10-01 11:14 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    What is your favourite meta-syntactic variable name?














    Results (8 votes), past polls