Releases and Update Status

In Drupal 5, the Update Status module was introduced (it was incorporated into Drupal core 6 as Update). As a module maintainer and release manager, it is important to know how the changes you make to your module's project page affect the unwashed masses running Drupal. This document will explain briefly how Update Status works, and then go on to summarize best practices for making releases.

How it works

Update status is smarter than you think. It knows what modules and versions a site administrator has (by reading the .info files), and it knows what modules are available (by checking drupal.org). With all this information, it calculates whether or not any of the modules need to be upgraded. It's not as simple as, "Aha! There's a new version! Upgrade now!"

First it is important to understand what the version numbers mean:

This pretty version corresponds to a specific tag in the CVS repository. This particular one corresponds to:

You can learn more about this naming scheme at the overview of contributions branches and tags.

• When any version that has a non-empty "extra" field is released (usually for alpha, beta or rc releases), Update Status will not nag the user to update. Instead, it will politely note that an additional, more recent version is available.
• When a security fix is released, Update Status goes into overdrive: it will email the administrators, mark the update panel with the big red letters "YOUR SITE IS INSECURE", and go the whole other nine yards.
• If a recommended branch which contains only "beta" releases (non-empty "extra") is selected, Update Status will pick the latest version even though it is not "stable".

Module release best practices

Some of these are related to the points above, some are not.

1. Always have a clear statement of intentions. If people misunderstand you, you are sure to get a spate of support requests that really shouldn't be there.
2. When you make a new release, make sure it is worth it for the users to upgrade. If you make a new release with every change, and your version numbers are something ridiculous like 5.x-1.45 (CVS tag of DRUPAL-5--1-45), people are going to yawn and say, "Well, you released 5.x-1.38 (DRUPAL-5--1-38) yesterday, so why should I upgrade now?" Of course, security releases should always be pushed as quickly as possible, but try to batch non-essential things.
3. "Extra" = Not stable. If you botch a release and need to re-release it, don't use version 5.x-1.2-1 (DRUPAL-5--1-2-1); Update Status will get confused and think that this is not a good release and should not be offered by default; increment to 5.x-1.3 (DRUPAL-5--1-3). This can trip up users who are used to an x.y.z version scheme, where z is patch level. For Drupal modules, y in x.y is the patch level
4. Use branches! These let you maintain stable and development versions simultaneously, letting you release bugfix versions without all that extra feature gunk

Do's and don'ts

End users get a bit leary when Update Status starts nagging them to update to an alpha or beta version. Consider these three case studies:

What To Do: The Case of Fairly Safe Widget

Fairly Safe Widget started off, as most modules do, with version 5.x-1.0 (DRUPAL-5--1-0). As the module grew, the developers realized that they ought to make some major changes. After a month of heavy cheese lifting and martini mixing, one beta and one release candidate, Fairly Safe Widget 5.x-2.0 (DRUPAL-5--2-0) was released and recommended to the general public.

Because there was no extra field in the version numbers, users saw, and they downloaded. A few edge cases were ironed out with 5.x-2.1 (DRUPAL-5--2-1).

Moral: Switch the recommended when you have an official X.x-Y.0 release without extra

What Not Do: The Case of Very Berry Baz

The very first release of Very Berry Baz, 5.x-1.0 (DRUPAL-5--1-0), was horrible and fundamentally flawed. So, the developers decided to do a complete rewrite of the code for 5.x-2.x (CVS branch DRUPAL-5--2). Once they had gotten the code into 5.x-2.0-rc1 (DRUPAL-5--2-0-RC1), they decided that this branch was far better than 5.x-1.x, even though it was alpha. So they went ahead and switched the recommended branch to 5.x-2.x.

In this case, even though users complained: "OH, YOU MUST NEVER, RECOMMEND, A NON-OFFICIAL VERSION URR!" the benefit of upgrading was large enough that the clamor settled down and after one more release candidate, the module went gold.

Moral: Don't make a beta or release candidate (rc) recommended, unless you have a *really* compelling reason, like the previous version is so broken that even the release candidate is better that that pile of cruft.

What Never To Do: The Case of Foolish Foo

After extensive upgrades to the code from 5.x-1.x (CVS branch DRUPAL-5), the developers decided they ought to set 5.x-2.x (DRUPAL-5--2) to the recommended branch. Presumably, this would increase their testing base. Unfortunately, they had only made 5.x-2.0-alpha2 (DRUPAL-5--2-0-ALPHA) release.

The next day, hundreds of Drupalites around the world woke up, and checked their highly profitable production Drupal websites. Being conscientious users, they had been checking their module updates regularly, so they saw Update Status dancing on fire, telling them:

Upgrade Foolish Foo to 5.x-2.0-alpha now!

"Alpha? Alpha?!?" An anguished cry arose from the earth. "How dare the Foolish Foo maintainers attempt to compromise the integrity my website with an alpha release!" The users wrote an angry issue note to Foolish Foo demanding their money back (Foolish Foo, of course, obliged).

Besides the absolutely terrible branding of this project, this is exactly what a maintainer should not do. Instead, Foolish Foo should have nicely asked their community to test the newer module version, without forcing it upon them with Update Status. There are always early adopters willing to lose some sleep over new features.

Moral: Never make an alpha recommended.

In Summary

Once again, unless you have very good reason for doing so, do not release beta/rc/extra versions as recommended and NEVER release alpha versions as recommended. These terms carry strong meaning in the development community, and should not be misused. Of course, if you have alpha-quality code, you should not release it as 5.x-2.0 (DRUPAL-5--2-0), otherwise users will come to distrust your code's stability and wait until 5.x-2.1 (DRUPAL-5--2-1) comes out before upgrading... to 5.x-2.0.

See also

Hat tip to Derek for most of the information in this document. You can listen to his original talk at BadCamp, "Talk on maintaining your Drupal modules".