Versioning Developer Releases
I finally stopped to think about how I’m numbering my developer releases for various modules I have floating around.
Two theories
Until recently I’ve always thought:
v0.0.5_1 is the first developer release leading up to v0.0.5
Something (sorry, I can’t remember what exactly) I read recently got me thinking about this and I started to think that maybe I’d got myself tied up into knots.
I started to wonder if the correct interpretation was actually:
v0.0.5_1 is the first developer release AFTER v0.0.5; working towards v0.0.6
I’m sure this is blindingly obvious to some people, but it was something I’d never stopped to properly thing about.
Investigation
After writing a quick script I came up with the following output:
.-------------+-------------+-------------+---------------.
| Input | normal() | cmp-prev | cmp-next |
+-------------+-------------+-------------+---------------+
| 0.0.4 | v0.0.4 | | < 0.0.5 |
| 0.0.5 | v0.0.5 | > 0.0.4 | < 0.0.5_01 |
| 0.0.5_01 | v0.0.5_1 | > 0.0.5 | < 0.0.5_50 |
| 0.0.5_50 | v0.0.5_50 | > 0.0.5_01 | < 0.0.5_99 |
| 0.0.5_99 | v0.0.5_99 | > 0.0.5_50 | > 0.0.5 |
| 0.0.5 | v0.0.5 | < 0.0.5_99 | < 0.0.6 |
| 0.0.6 | v0.0.6 | > 0.0.5 | |
'-------------+-------------+-------------+---------------'
Conclusion
As you can see, the non-developer release numbers compare as expected.
0.0.5 was put before and after the 0.0.5_xx versions for comparison at both ends.
As you can see,
v0.0.5 is less than < 0.0.5_01
and
v0.0.5_1 is greater than v0.0.5
This matches my newer, second hypothesis:
v0.0.5_1 is the first developer release AFTER v0.0.5; working towards v0.0.6
Why does this matter?
For the most part, most people really won’t care … or even notice. I’ve been getting this wrong for as long as I can remember and haven’t been adversely affected.
However, if you want the progression of your code to ‘make sense’ with the progression of your version numbers it’s important to get this right.
Also, although untested, I’m fairly confident that if you have some poor soul brave enough to try out your v0.0.5_1 release and after a few iterations you’re happy with the results and release v0.0.5 ‘final’ you’re doing a disservice to the brave soul who’ll never ‘upgrade’ to your lower version numbered release.
Thanks for this post. You know what, I used to think that way too :) Most certainly it's the influence of the common convention 1.2alpha, 1.2beta, et al which in semantic versioning *is* smaller than 1.2. Fortunately I've never done a developer release, so this confusion is avoided.
BTW, PAUSE does not index dev releases, so we can happily upload 0.05_01 or 0.06_01, even though there is (or isn't) 0.05 and 0.06.
And I would argue that we remove/adjust Changes entry after the final releases. So if we release 0.05_01, the Changes contains entry for 0.05_01. Later after we release 0.06, the Changes entry for 0.05_01 should be merged into 0.06.
To avoid uncertainty I usually use separate version for development releases: 0.04, 0.05_1, 0.05_2, 0.06
Thanks for confirming I wasn't alone in this :)
I realise that it's extra work for people to choose to install a developer release, but I didn't want to make life even more difficult for them when the release was finalised.
I like the idea of having dev releases with individual entries in the Changes ... and then merging them into one combined list when the non-dev release is made.
Sadly I realised the versioning mistake, and read your suggestion far too late for the module that had to live through this thought process.
Next time ...
Yeah, I accidentally did this for the module I was working on while these thoughts were solidifying.
I've accidentally turned the module into odd-developement/even-stable versioning, but I'm not sure that how I'd like to stay.
Now that I've crowbarred the understanding into my head I think I'll go from v0.0.6 to v0.0.6_01
Looking at it now it's an obvious progression for me.
This is how I version my software:
0.001_001 # dev release 1
0.001_002 # fix bug
0.001_003 # fix missing dependency
0.002000 # first "stable" release
0.003_001 # new feature
0.003_002 # fix bug
0.004000 # effectively 0.4.0
http://www.dagolden.com/index.php/369/version-numbers-should-be-boring
https://blogs.perl.org/users/davewood/2011/12/cpan-my-first-time.html
I try to avoid thinking about version numbers as much as possible.
The first release is generally 0.001 and thereafter I use "perl-reversion --bump" for each release. On rare occasions I'll bump up to a round number to indicate more of a milestone release.
If I feel the need for some developer releases, I'll go 0.004 -> 0.005_01, 0.005_02, etc -> 0.006. If I need developer releases before 0.001, these are usually 0.000_01, 0.000_02, etc.
I don't obsess about trying to make sure all my projects use the same one true versioning scheme.
Some people replied that they do the odd/even thing. I take the current version and start stacking dev releases on it until I bump the stable version:
1.001 #release
1.001_01
1.001_02
1.002 # release
I don't have any particular reason for doing it that way.
Just please do not include the 'v' in your version string -- see http://www.dagolden.com/index.php/369/version-numbers-should-be-boring
The 'v' is only display level - I promise :)
https://metacpan.org/source/CHISEL/WebService-NotifyMyAndroid-0.0.6/lib/WebService/NotifyMyAndroid.pm#L4
$WebService::NotifyMyAndroid::VERSION = '0.0.6';
Thanks for pointing out this subtle, but important factoid. I also highly recommend reading Dave Golden's treatise on version numbers:
http://www.dagolden.com/index.php/369/version-numbers-should-be-boring
The documentation for version.pm is also very good reading material. It is important to understand the differences between decimal and dotted-decimal version numbers.
Just found this link (by googling "cpan developer release")
http://www.cpan.org/modules/04pause.html#developerreleases
It is actually all explained there.
Thank god I know now. It happened so often to me that I uploaded a release and found out days later it was broken. I did not know of this functionality.