Dear Matt/Automattic/Akismet

Posted in Software at 10:36 pm by

Warning: this is a little bit of a rant.

Sometimes I wonder if WordPress plugins [sic] exist to make practitioners of the Apple School of Release Notes™ look good. Most of the time I’m lucky if I can find any indication of what might have changed in a plugin, despite the WordPress plugin upgrade UI leading me to believe this information is only a click away (right inside my own WordPress install, even).

As an example, here is the upgrade notice for WordPress shepherd/developer Matt Mullenweg & Automattic’s signature plugin, the Akismet spam catcher.

The upgrade notice inside my WordPress install includes a link entitled “View version 2.2.5 Details” for the upgrade to Akismet 2.2.5, which sounds like it would provide details such as changes in this version:

WordPress 2.8.1 upgrade notice for Akismet, with “View version 2.2.5 Details” link

Clicking on the aforementioned “Details” link shows this screen, where I find “useful” information like the latest version number, date last updated, number of downloads, and author and plugin webpages (as well as the oh-so-helpful installation instructions, should I not want to let WordPress install the upgrade automatically):

WordPress 2.8.1 upgrade UI for Akismet 2.2.5, showing aforementioned “Details”

If I click on the “WordPress.org Plugin Page” link, I’m presented with the WordPress.org page for Akismet; surely that will tell me what’s new or changed in Akismet 2.25, right? Nope, this page looks suspiciously like the “Details” page I just left:

WordPress.org Plugin Page for Akismet

Finally, I click on the “Plugin homepage” link and arrive at Akismet.com. From there, I see options like “Download”, “FAQ”, “Development”, and “Blog”, and, since this is not my first go-round with an Akismet upgrade, I know that only “Blog” might contain information about this new version. Indeed, I’m in luck; New plugin version 2.2.5, currently the first post on blog.akismet.com, has some details.

Four clicks after I began (and four domains later), I have what it seemed like the very first click promised me (in fairness, I could have saved a click by going directly to the “Plugin homepage” instead of visiting the “WordPress.org Plugin Page” link, but I also saved a number of clicks by remembering that “Download”, “FAQ”, and “Development” wouldn’t contain information about changes in releases).

Frankly, this sucks. But guess what? It doesn’t have to suck; according to this Weblog Tools Collection post from nearly a month ago, WordPress supports a standard method of including a “Changelog” tab in both the WordPress.org page (the third screenshot above) and the WordPress “Details” view (the second screenshot) for plugins with upgrades available.

The fact that this great feature is available for WordPress plugins but hallmark plugins like Akismet (2.2.5 was released on July 13, nearly three weeks after the posts about the “Changelog” feature) aren’t using it sucks even more. To add to the irony, the WordPress.com page for Akismet lists “mdawaffe” as an Akismet author, and the Weblog Tools Collection post credits “mdawaffe” as one of the key contributors (implementors?) of the new “Changelog” feature on the WordPress end! :shock:

Please, Matt, Automattic, and Akismet, take up the mantle in this area; implement the Changelog in Akismet upgrades and lead by example, as a hallmark plugin should. Thank you.

Smokey Ardisson
voracious consumer of release notes


  1. User Grav­atarDave Miller said,

    07.16.09 at 1:07 am

    Hear hear! I was just thinking this myself as I upgraded a bunch of plugins on my wordpress the other day.

  2. User Grav­atarSimon said,

    07.16.09 at 1:36 am

    Agreed – well-written release notes are something far too many projects lack. All too often, the only way to find out what a patch-release has changed is to download it and try to make sense of a Changelog file generated from SVN commit logs.

    Some Gnome packages provide separate ‘changes’ and ‘news’ files, which is good – the former is the full commit history since the last release, while the latter is a much-summarised version, stuff like “Fixed crasher bug when XYZ” or “Translation updates for Turkish”. If only more did that.

  3. User Grav­atarAlex said,

    07.16.09 at 7:55 am

    Hi Smokey,

    We have been posting detailed release notes on the Akismet blog, as you eventually found, but we inexplicably overlooked the new plugin changelog system.

    Akismet now has a changelog here, where it should be.

    I can’t promise it’ll make interesting reading, but I promise we’ll keep it accurate and up to date.

  4. User Grav­atarSmokey said,

    07.16.09 at 11:52 am

    Thanks, Alex, for getting the changelog up for Akismet—and so quickly, too! Since “everyone” uses Akismet, I hope that seeing the changelog there will help remind other plugin authors to include one with their releases.

    You’re right, release notes/changelogs aren’t often riveting reading, but they are important, and I really appreciate the fact that Akismet has been posting changes on the blog all along and will be keeping the new plugin changelog accurate and up-to-date going forward. Thanks again!

  5. User Grav­atarSmokey said,

    07.26.09 at 7:15 pm

    The WordPress Blog has a post about the Changelog feature, too. :)

    Thanks to Peter Westwood for his work on the feature and for the aforementioned high-profile post about it last week.

Atom feed for comments on this post · TrackBack URL

Leave a Comment