Changelogs, Changelogs, Changelogs

A Changelog is a very important thing for a project and until recently it wasn’t easy to add one to your WordPress plugin hosted in Extend.  Some plugin authors understood the benefit of providing there users with the information and were adding it in different places but it was not easy to track down where it was and it some cases your only hope was a trail of clicks across the web to the plugin Authors site to hunt down the post detailing what had changed in this version.

For me, a changelog is a very important thing it is all about justifying to your users why they should upgrade to the latest version of your plugin as well as reassuring them that the changes made have been made for specific reasons and helping them to understand the impact the changes may have on there usage of your plugin.

This has been a hot topic of late and we were discussing it on last nights WP Weekly podcast so I set off to see if I could track down the right person to get a change made to give all plugins a separate top level Changelog tab on there WordPress extend page.

This morning to my delight I found that a Changelog feature had been added and now we have a standardised way for plugins to add Changelogs.  Basically there is a new section in the readme.txt standard which allows for you to document your changelog as your plugin develops.  The new section looks like this:

== Changelog ==

= 1.0 =
* A change since the previous version.
* Another change.

= 0.5 =
* List versions from most recent at top to oldest at bottom.

Which produces the follow style of display on the plugins page in Extend:

Example of the changelog output
Example of the changelog output

And the information will also be displayed in a separate tab in the administration section of your WordPress blog by the plugin installer and updater:

The view of the changelog in the WordPress admin pages
The view of the changelog in the WordPress administration pages

So please go forth and update your plugins readme.txt file and let your users benifit from the information about what has changed between versions.

46 thoughts on “Changelogs, Changelogs, Changelogs

  1. This is a great addition. I added a changelog link to my plugin during the show when Jeff posted the information about how to add one.

  2. Great work Peter on getting in touch with the right man at the right time to have this issue resolved. I think this is one of those small changes which reap large benefits for the WordPress community.

  3. All plugins i host at wordpress.org/extend/plugins/ published after January 2009 got at their “other notes” section exact this layout of change log you are now providing.
    I’m happy to see, that we have now a dedicated prominent place to show such important information.

  4. As a plugin author and user, this is a very nice addition. I hate having to update plugins when the change did not do anything that will effect me. I also hate having to decide how to display the Changelog to my plugins’ users. It will be nice to have this standardized.

  5. That’s great news! I was waiting for this for so long since version info are the first I am seeking before updating a plugin.

    I’m about to release a plugin that displays version info for the latest version of a plugin in the plugin list without having to open the thickbox and browse to the changelog tab.

  6. FINALLY! I’ve been waiting and waiting and waiting for a standardized model for changelogs, I’m glad it’s finally here.

    I’ve been begging and begging for chanelogs to be integrated into the upgrade process to decipher whether I really needed to upgrade or not.

    Thanks for reporting on this Westi, I really appreciate it.

  7. Could someone give me a pointer to the script used to format the readme.txt file?

    I would really appreciate it!

    I have looked around a bit, can’t find any reference to it. I’m probably missing something obvious.

    Thanks!

  8. I would prefere also an inverse sorting order, i have changed this during my latest update today. If the version list is growing, it makes more sence to have the newest version on top instead of bottom to avoid scrolling during the dashboard installions for miles :-)
    Would you agree, that this is better sorting order also to be proposed ?

    1. I can see the arguments both ways.

      I suspect the code that handles it can cope with both and I guess it depends on how long it gets.

      While it is short I think I would prefer it to be in chronological order with the first version at the top. Once it gets long I can see and argument for reversing the order to make it easier to read the changes that happened in the latest version.

      I think it is down to plugin author preference really as both work fine.

  9. Peter, thanks.

    The formatting is a markdown variant IIRC, which isn’t too much of a problem to find parsers for.

    However, somebody, somewhere, has to be parsing the markdown to extract “Changelog,” “Installation,” that sort of thing.

    My interest is in adapting that script for use in my recipe plugin. It would save me a week of work, at least.

    Thanks again for your reply!

    1. The best people to talk to would be Mark Jaquith and Michael Adams as they were the people that put the validator together in the first place and I think the parser used by Extend is a development on from that.

    2. The parser is located at http://code.google.com/p/wordpress-plugin-readme-parser/

      We use a checkout of trunk for the Plugins Directory on Extend. It just pulls out the data via some regexes and returns an array. I don’t think it’d be terribly useful for generic parsing, but you may be able to grab some regexes from it.

      You’re right in that the format is essentially Markdown (with some MediaWiki style headers thrown in for good measure).

      1. Thanks Michael!

        I was sure the code would be out there somewhere just couldn’t find it with the power of google.

        Of course now I know what to search for it’s the top result!

Comments are closed.