Module version numbers best practice

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

The time has come to publish a module on CPAN (hurrah!) and in cleaning up the code in advance of publication the need has arisen to choose a version number system. Unfortunately the documentation which I have found (much of which is well out of date) is unclear and/or contradictory so I humbly ask for your thoughts and advice.

The documentation for version suggests that there are only two options, the dotted decimal (1.23) and the v-string (v1.2.3). I would like my module to be useful to the widest extent and this prejudices me against the latter because it requires another non-core dependency in pre-5.10 versions of perl. Of course this is a minor point but if there's no real advantage to v-strings why make extra work?

The older docs here at PM such as Simple Module Tutorial seem to be happy with dotted decimal (but see the first subthread for discussion on this). The (slightly) more recent José's Guide for creating Perl modules is equally happy with it and describes the traditional 1.23_45 format for dev releases which seems to me to be both widespread and sensible.

So, the question is this. Is there anything inherently problematic with dotted decimal either now or that could be reasonably foreseen? Thanks for any advice you can give.

Hippo

Update and Summary

Thanks to everyone who responded - your advice is much appreciated. There seem to be reasonable levels of support for both date-based versions and traditional dotted-decimal and some lesser support for v-strings.

I've decided to go for dotted-decimal in this particular case for reasons of simplicity, backwards compatibility and legibility. The expectation (rightly or wrongly) is that development of the module won't be rapid so two digits will suffice for minor versions (eg. 1.01_01) which I think is the best compromise in the circumstances.

Finally, thanks to admiral_grinder who makes an excellent point. I too have been caught out by this in third-party bundles in the past and will therefore strive to avoid such confusion in my own code.

Comment on Module version numbers best practice

Replies are listed 'Best First'.
Re: Module version numbers best practice (KISS) by tye (Sage) on Oct 18, 2013 at 18:30 UTC
Don't use version.pm and don't listen to Perl Best Practices on this one. This is a classic example of somebody writing up a recommendation on something brand new (the author's own creation). A few months of experience showed problems with the idea, but it isn't like the book is going to be republished to discuss those. Make your version numbers very simple, values that can be interpreted as numbers and that always sort the same whether treated as numbers or as strings. Avoid trying to assign meaning to your version strings or parts of them. So I just always follow Perl's lead and use 1.001_001 forms of version numbers. Though I avoid Perl's idea of assigning meaning to whether or not the middle part is odd or even. I also skip multiples of 10 for the 2nd and 3rd parts and don't let the third part go above 99. If the 2nd part goes above 99, then I skip to 111 to avoid the second digit being 0. This is so the break-up is obvious even when the '_' is not present because you are seeing just the numeric value. If you expect to get past version 9, then you should start with version 10 so you can avoid string sorting breaking down when you go from 9.x to 10.x. Set you version number very simply such as via: `our $VERSION = 100.001_001;` [download] so all of the different things that try to introspect for your version number without running your code have no problems. - tye	[reply] [d/l]
Re^2: Module version numbers best practice (KISS) by BrowserUk (Patriarch) on Oct 18, 2013 at 19:09 UTC
Make your version numbers very simple values that can be interpreted as numbers and that always sort the same whether treated as numbers or as strings Avoid trying to assign meaning to your version strings or parts of them. use 1.001_001 form avoid Perl's idea of assigning meaning to whether or not the middle part is odd or even skip multiples of 10 for the 2nd and 3rd parts don't let the third part go above 99 if the 2nd part goes above 99, skip to 111to avoid the second digit being 0. If you expect to get past version 9, then you should start with version 10 8 steps to simplicity :) With the rise and rise of 'Social' network sites: 'Computers are making people easier to use everyday' Examine what is said, not who speaks -- Silence betokens consent -- Love the truth but pardon error. "Science is about questioning the status quo. Questioning authority". In the absence of evidence, opinion is indistinguishable from prejudice.	[reply]
Re^3: Module version numbers best practice (KISS) by LanX (Saint) on Oct 18, 2013 at 19:21 UTC
Better addressed to the OP? Cheers Rolf ( addicted to the Perl Programming Language)	[reply]
Re^4: Module version numbers best practice (KISS) by Anonymous Monk on Oct 19, 2013 at 03:03 UTC
Re^5: Module version numbers best practice (KISS) by BrowserUk (Patriarch) on Oct 19, 2013 at 07:01 UTC
Some notes below your chosen depth have not been shown here
Re^4: Module version numbers best practice (KISS) by BrowserUk (Patriarch) on Oct 18, 2013 at 19:24 UTC
Re^5: Module version numbers best practice (KISS) by LanX (Saint) on Oct 18, 2013 at 19:26 UTC
Re: Module version numbers best practice by marinersk (Priest) on Oct 18, 2013 at 17:34 UTC
While I personally like the v-string standard for human-readability, the facts already presented in this thread strongly suggest the dotted-decimal system would find the most widespread use -- and reducing your pre-v5.10 non-core dependencies can only be of benefit. For personal version control I version everything with a timestamp similar to, but not quite exactly like, ISO 8601, and since almost everything on my system has this, and I have a bunch of tools written which make manipulation of these files very, very easy, I'm disinclined to change my personal standard -- but I also don't expose it to other people unless they are watching me type `:-)`. Example: `P-2013-10-18@1131-Alternate-Universe-Project.docx` I suppose I could bring myself some free weekend to convert all my tools to ISO 8601 and it wouldn't take long to adapt. I'll have to think on that. But I think the evidence is overwhelming that the answer to your question is likely to be dotted-decimal.	[reply] [d/l] [select]
Re^2: Module version numbers best practice (meaning--) by tye (Sage) on Oct 18, 2013 at 18:38 UTC
Using dates as version numbers still runs into the problems of trying to assign meanings to version numbers. For example, there was a module on CPAN that went to using the integer part of the version number as the year. And then they didn't notice that they had accidentally used next year until they had already uploaded that version to CPAN. This meant they couldn't release anything new with their desired version number scheme for a long time. - tye	[reply]
Re^3: Module version numbers best practice (meaning--) by Bloodnok (Vicar) on Oct 21, 2013 at 10:05 UTC
The principles of CM merely require that CIs (configuration items) have a means of identification such that different CIs and different compositions/versions of those CIs be readily distinguished. In the case of perl, the CIs are modules whose name distinguishes them apart from other modules and `$VERSION` distinguishes between the versions of a module. Whilst not mandated, it is conventional that the versioning scheme readily supports the determination of the temporal ordering of the individual CI versions. To this end, as has been stated elsewhere, the versioning scheme of choice should follow the above whilst allowing for the nuances of perl in it's interpretation of the version identifier. FWIW, my preference is to utilise an ISO 8601 style time/datestamp with all separators removed thus removing any mis-interpretation (pun intended) by perl since all version ids are merely, albeit lengthy, integers whose value specifies when the module was checked in i.e. became repeatable. The use of ISO 8601 c/w epoch timestamping, future proofs the versioning against the epoch roll-over. Just my 10 penn'orth A user level that continues to overstate my experience :-))	[reply] [d/l]
Re^3: Module version numbers best practice (meaning--) by marinersk (Priest) on Oct 18, 2013 at 20:23 UTC
----------------------------------------------------------------------------------^ `tye` is right `tye` is justified `:-)`	[reply] [d/l] [select]
Re: Module version numbers best practice by Anonymous Monk on Oct 18, 2013 at 16:29 UTC
Few things to consider ... a syntax that does not cause a higher version to be interpreted as a lower one (happened in case of Opera); e.g.: 1.01 != ( 1.1 = 1.10 ) & 1.01 < ( 1.1 = 1.10 ); a syntax which would allow easy sorting outside of perl software. BTW, what is the problem with using ISO 8601 dates as version number?	[reply]
Re: Module version numbers best practice by toolic (Bishop) on Oct 18, 2013 at 16:29 UTC
Refer to the "Version Numbers" section in the Perl Best Practices book (not sure if there is a free, legal copy anywhere.)	[reply]
Re^2: Module version numbers best practice by keszler (Priest) on Oct 18, 2013 at 17:21 UTC
According to Perl::Critic::Policy::ValuesAndExpressions::ProhibitComplexVersion The construction `use version; our $VERSION = qv('1.2.3');` is exempt from this policy by default, because it is recommended by Perl Best Practices.	[reply] [d/l]
Re: Module version numbers best practice by DrHyde (Prior) on Oct 21, 2013 at 10:44 UTC
Given that you have asked for help choosing a "version number system", I think you have answered the question yourself. 1.2.3 and v1.2.3 aren't numbers. Therefore they aren't version numbers. Therefore they are not what you want.	[reply]
Re: Module version numbers best practice by admiral_grinder (Pilgrim) on Oct 23, 2013 at 16:08 UTC
A suggestion to make it easier for your users in package management. Please sync the version numbers of your CPAN package with the version that your entry module uses. I have had to spend many wasted hours downloading and comparing version numbers across several modules just to determine what package release was being used. If your package is a collection of tools, then perhaps a bare module named the same as the tool collection to contain this version number. (Just off the top of my head, I have no good ideas for this case)	[reply]