NEILB's Blog

Semantic versioning defines a scheme for MAJOR.MINOR.PATCH version numbers. There's a SemVer module on CPAN, and some people have started switching to semantic versioning for their modules. I think this is more complicated than at least 99% of dists need.

The version module and v notation are also too complicated. Read David Golden's post on version numbers for more details.

I think most people can get away with a simple scheme, which will be easier for humans to understand, and easier for code too:

• The first version of your module should be 0.01. Yes, we all know arrays start at 0, but this could lead to subtle bugs, and I can't see a good reason for starting a version at 0.
• 0.NN when you're still working out the interface for the module.
• Add _NN for developer releases. Note: if your first releases are all developer releases, then PAUSE won't assign the namespace to you until you do your first non-developer release.
• Once you've firmed up the interface, move to 1.00.
• Thereafter, bump the major version for major changes, or backwards incompatible changes to interface.
• Bump minor version number for all other releases.
• Go to three digits (ie 0.NNN) only when you need it. If you find yourself getting to 0.90, then consider going to three digits, eg 0.901. This way, when someone sees that style of version number, they'd know the module gets released a lot / often.

This is roughly what's described in perlmodstyle, but with more specifics.

The toolchain just cares that version numbers are monotically increasing, and needs to be able to distinguish dev releases. Everything else should be easy for humans to understand. People trying to process version numbers programmatically will get tripped up over the X.Y.Z version numbers.

The version scheme described above is by far the most widely used on CPAN. Here's the distribution of version number formats in 02packages.details.txt (code) as of 2013-07-17:

64.48% \d+\.\d{2}
 9.48% \d+\.\d{3}
 7.57% \d+\.\d{1}
 6.34% \d+\.\d{6}
 5.83% undef
 3.14% other
 2.35% \d+\.\d{4}
 0.69% \d+\.\d{5}
 0.12% \d+\.\d+\.\d

I think it's pretty clear what the "standard" for CPAN is.