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?

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:

• Excel-Template
• ExtUtils-MakeMaker

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.

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.

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.

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?

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).

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

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?

: 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.)

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.

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