Releasing: making it hard¶

Tags: buildout, zestreleaser

There’s a bit of what I’d call a culture clash on the zope.dev mailinglist. About version numbers. Not the deepest subject, but one we as developers have to deal with all the time.

• Current common case, especially in zope/plone/grok land: if you just released a 1.2, you mark it 1.3dev immediately afterwards. When you next release the package it becomes 1.3. Or you change it to 1.2.1 if it has to be a bugfix release. (But in that case you probably made a 1.2 branch for those bugfixes, so you changed it to 1.2.1dev already).

• In violation of above (written down!) standard, several zope packages now have a version of 0 when in development. So 1.2 to 0 to 1.3. The proponents of this like it as you’re forced to look up the proper new version in the changelog and the svn log. The extra pain is good.

• A commonly used alternative is to use setup.cfg to automatically add svn revision numbers to the version. You’ve got to remember to switch that off again when releasing (which collective.releaser does for you). I dislike it as there are quite some 1.2-r1234 packages on pypi. Junk.

• I haven’t seen it yet in python land, but someone suggested to mark the post-1.2 as 1.2+svn instead of 1.3dev. This explicitly leaves open the option of turning it into a 1.2.1 or 1.3 or 2.0. Apparently used by debian for instance. Pretty elegant if you tell me.

Some drawbacks of the ‘0’ approach:

• It is more work. The proponents think this is good. But what’s the point of having 9 instead of 8 manual steps? Releasing is still a chore.

• You can no longer specify a minimal version requirement in packages that use the library. No more my.package > 1.2 to signal you really need that newest now-under-development package. Yes, you can set it to my.package == 0, but that means several extra steps. This way you’re basically inviting people to just be lazy and forget about it. (And I guess it breaks packages that specify ANYTHING that’s higher than 0, but it might be a special version requirement edge case).

• You lose information. You’re relying on error-prone human beings to keep in mind that this is supposed to be 1.3 instead of the 1.4 you saw just 3 minutes ago when releasing the other package. The 1.3dev would have served as a warning sign. Yeah, you have to look in the changelog, but the error is just as easily made there.

So: please forget about making the release process 10% harder if it costs you this much. A better approach is to use for instance zest.releaser (disclosure: which I wrote a big part of). This simple unobtrusive tool:

• provides a lasttagdiff script to make it easy to check the changes made since the last tag so that you can update the changelog,

• never forgets to write down the day of release in the changelog,

• simply suggests the current version (1.3 in case the version is 1.3dev) as release version number, but allows you to change it,

• shows you the changes in setup.py and CHANGES.txt and asks approval to help you double-check yourself,

• never forgets to tag the release

• never forgets to upload the release to pypi (if applicable)

• never forgets to increment the version number after the release (doing a suggestion and allowing you to override),

• never forgets to also add a new section to the changelog.

My experience (and zest software’s and the health agency’s and many more developers): such a tool removes a lot of common mistakes and prevents a lot of errors and propagates good release practice. It invites you to make a proper well-checked release.

Ok, end of sermon :-)