Skip to content

Incomplete release notes and putting people off

There is a risk that this is going to sound like a bitch. It’s not, I promise. Getting the release notes right when you are tracking tens or even hundreds of developers is nigh on impossible. That said, I need to get this off my chest…

One of my niggles with Plone over the 2 years that I’ve been using it has been that upgrades to apparently minor versions have sometimes had major and unexpected effects. Unexpected because the release notes simply haven’t made it clear that particular changes have been included. The one that leaps immediately to mind was the change from 2.1.2 to 2.1.3. All sorts of things changed not only under the hood but also in the UI, making what appeared to be a fairly minor release suddenly a blocker on the project we were working on at the time.

Since then I’ve been very wary about changing versions of Plone mid project, even when the documented release notes show very few changes. The problem for me is that the release notes do not show every change. Even the relatively detailed release notes for the 2.1.3 release didn’t include all of the changes that were made that directly impacted our project, and the notes for later releases contain even less (see, for example, the ones for 2.5.4).

We recently found a nasty bug in Plone 2.5.3, where users couldn’t register if their desired username was contained within the username of another user. E.g. if a user with username freddy already existed the usernames fred and eddy would both cause the The login name you selected is already in use or is not valid. Please choose another message when a user tried to register with them. The bug appears to have existed throughout the Plone 2.5.x releases until 2.5.4, when it was identified and fixed.

This is major bug. Any Plone site at 2.5.3 or lower with a medium number of users is going to hit this problem. Here at Isotoma our first port of call is to start hunting down the bug, but most Plone deployments aren’t done by people with such intimate knowledge of the code base. Most people’s first port of call will be to see if this bug is fixed in later versions. In this case it was, but the release notes didn’t mention it.

So. If I’m a Plone deployer (rather than developer) who’s not comfortable with the source do I a) upgrade in the hope that my bug might be fixed in the latest version (and not knowing what else might have changed), do I b) stick with the version I’ve got and work around the problem, or do I c) think seriously about an alternative CMS that tells me when my bugs been fixed?

What I’d really like to see is a simple list of all tickets that have been closed and all the commit messages that have gone into a particular release. Trac (which the Plone team uses at dev.plone.org) has this ability to do this right now (here are the tickets for 2.5.4, for example) – all we need are the links on the release page so that those users that aren’t developers and aren’t comfortable with the tools we use have easy access to the information they need to assess if and when to upgrade.

Limi (the Plone project lead) recently posted 18 Things I wish were true about Plone. Number 1 is Simple development should be possible entirely through the web interface. This really talks to the pretty much constant discussion within the Plone community that the product can be hard to get started with and that it feels like you need to be a developer to use it.

I can’t help but feel that incomplete release notes are a part of this problem. For the want of just a little extra Trac magic and the judicious placement of links this wouldn’t be a problem.

As an aside… While writing this post I wondered how the Drupal team handle it. They do, indeed, do it differently. They provide detailed ticket based release notes for each release and easy links into their CVS for each main branch. I kind of wish they didn’t, to be honest…