Releasing: making it hard
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 :-)