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.

11 Comments

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

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

http://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

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.

Leave a comment

About Chisel

user-pic I blog about Perl.