Version numbers on trunk and maintenance branches

July 19, 2008

The release process that I wrote for the Zope subversion repository states that a library’s version number on the trunk or a release branch should always be the next release version number applicable to that branch. For instance, if zope.interface 3.4.1 were just released from the 3.4.x branch, the version number of zope.interface on that branch should read 3.4.2dev.

Let me explain why I suggested this practice and, despite much critique, still maintain it’s makes the most sense.

First of all, the setuptools documentation states:

Note: the project version number you specify in setup.py should always be the next version of your software, not the last released version.

So it’s a convention that seems to be generally suggested. That doesn’t necessarily mean it’s a good idea, though.

What makes it a good idea is the fact that when you get a checkout of the trunk or a development branch, the version number is actually meaningful, due to setuptools’ version semantics

3.4.1 < 3.4.2dev < 3.4.2

So, a development egg of zope.interface 3.4.2dev will for instance satisfy a version requirement like “zope.interface > 3.4.1“. For example, say you wanted to temporarily deploy from a subversion checkout. I had to do this to get my PyFlakes running with Emacs. The latest release PyFlakes 0.2.1 wasn’t good enough because something got fixed on the trunk. So I got a trunk checkout and did a

python setup.py install

into a virtualenv. Surely enough, the trunk’s version number was still pointing to 0.2.1. So I ended up with pyflakes-0.2.1-py2.4.egg in my site-packages and no way to tell it from the actual 0.2.1 release. (Yes, I know there’s some setuptools parameter than can let you build versions like 0.2.1-r48292, and those would be fine, if they were configured to occur on the trunk automatically.) So that’s why not only bumping the version number to the next release but also adding the “dev” marker to tell development eggs or snapshots apart from actual release (and prevent people from releasing from the trunk!) is a good idea.

To conclude, I think bumping the version number to the next or at least the next anticipated release (it’s ok if you don’t get the version number right the first time) and adding a dev marker is not only a good idea, I think it’s pretty much the only way to get the version number semantics of development eggs right (unless you use r34234 suffixes which have other problems). Of course, I’m willing to be convinced otherwise if alternate solutions achieve the same semantics. Comment away!

3 Responses to “Version numbers on trunk and maintenance branches”

  1. Ben Finney Says:

    > What makes it a good idea is the fact that … the version number is actually meaningful, due to setuptools’ version semantics

    That’s all well and good if setuptools is the only thing that compares version numbers to one another. What about an operating-system package manager? What about some external tool looking at version numbers on file archives? What about the application itself?

    The version number should be *trivially* comparable, precisely so we don’t have to rely on one particular tool in order to hope to get the right “semantics”. Why not just choose version numbers that compare correctly in alphanumeric sequence?

  2. philikon Says:

    That would work for me, too, as long as a trunk or branch checkout did not contain a version number that could be confused with a release version number. Setuptools just happens to support this neatly with the ‘dev’ marker.

  3. Wichert Akkerman Says:

    Unfortunately setuptools has a very magic version version comparison algorithm which no package manager will ever support. It’s handling of a, b, c and rc is too magic.


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: