WordPress Plugin Developers Need to Communicate Better in Change Logs

Communication Featured Image
photo credit: elycefelizcc

One of the habits I developed when I started using WordPress is to always read a plugin’s changelog before updating. The changelog is a communication channel that bridges the gap between me and the developer.

It tells me what’s changed, what to expect, and any other information the developer thinks I should know. The most important information a developer can tell me is that a security vulnerability has been addressed.

Security vulnerabilities in WordPress plugins generally receive a decent amount of media coverage. If I read a story that mentions a plugin I use containing a vulnerability, the first thing I do is visit that plugin’s changelog on the WordPress plugin directory to see if it’s fixed. However, some plugin authors don’t do a very good job of informing users that a security patch has been applied.

WooCommerce and VaultPress

WooCommerce recently released an update to fix an object injection vulnerability. If you look at the changelog for 2.3.11 which has the patch, there is no mention of a security vulnerability being fixed.

2.3.11 – 10/06/2015

  • Fix – Check if rating is enabled before check if rating is required to a review.
  • Fix – get_discounted_price needs to check if taxes are enabled.
  • Fix – Fixed filetype check for digital downloads.
  • Fix – Newfoundland and Labrador state rename.
  • Fix – Escaped js in widget layered nav when use the dropdown option.
  • Fix – Switch the permissions check for json_search_products to use the read_product capability.
  • Fix – Fixed the addition of variable products using the Order API.
  • Fix – Sale item exclusion logic for variations.
  • Fix – Clear correct variation stock transients when setting stock.
  • Fix – Switch to JSON to avoid unserializing untrusted data when handling responses from PayPal.
  • Fix – API – Fixed the sanitization for downloadable files on products endpoint.
  • Tweak – woocommerce_downloadable_file_exists filter.

To the untrained eye, 2.3.11 is just a regular maintenance release. Security fixes should be front and center and command attention.

VaultPress, a security monitoring plugin by Automattic, also fails to provide clear information in its changelog. Determining security patches with VaultPress is confusing because security hotfixes are labeled as though they are patches for the plugin itself. Instead, security hotfixes are patches to protect from known security vulnerabilities.

1.7.5 – 11 Jun 2015

  • Security: Add a new security hotfix.

1.7.4 – 28 Apr 2015

  • Bugfix: Don’t allow openssl signing unless the public key exists.

1.7.3 – 27 Apr 2015

  • Security: Add a new security hotfix.

To add to the confusion, there’s no explanation as to what the hotfixes protect against. You have to read the inline comment on GitHub to know what the latest hotfix does.

// Protect WooCommerce from object injection via PayPal IPN notifications. Affects 2.0.20 -> 2.3.10

If VaultPress developers added the comment from GitHub to the changelog on WordPress.org, it would have made things a lot clearer.

Users Read Change Logs

When we asked readers how often do they read a plugin’s changelog before updating, 705 out of 1,152 voters said they always read it while 338 people said they sometimes read it. Whether they understand the changes or not, users read change logs.

If you’re a plugin developer, please consider adding context and clear explanations to your change logs. Clearly state what is a security patch, bug fix, or tweak. I don’t need to know the fine details, just enough information to make a good decision.

40 Comments


  1. This needed to be addressed. Thank you Jeff and thank you developers for documenting your changelogs carefully. I read them before every update. In fact one of my plugin authors uses it as a tool to educate the users on new features, updated options, etc. Very helpful indeed!

    Report


  2. Great topic Jeff! I think we all could benefit from improving our changelogs. Nothing frustrates me more than seeing “Fixed a bug” or “Added some new features” on a changelog. I want to know some more details than that. Of course, I probably should improve my own changelogs as well!

    Report


  3. Yes, yes, and yes. I couldn’t agree more. Have you seen our changelogs? They’re pretty verbose. This should be standard practice. This is not a minor detail to pass over. Many people, like Jeff, read the changelogs prior to updates and it’s critical to explain in as much detail as possible what has changed.

    Report


  4. Agreed! Before any update i check whats in store. This needed to be adressed.

    Report


  5. I agree with this 100% as well. I have to admit that I haven’t always been as verbose in my changelogs as I could be, but I’ve been following the various discussions about it here, and I’ve been more descriptive.

    The failure to mention security fixes is one thing that really bothers me. I for one always make sure to mention when a security issue is fixed. But I’ve noticed that many plugins don’t. Among these are bbPress and BuddyPress. Though when I reported some vulns in bbPress, it was mentioned in the announcement post for the release.

    I should note that the post for the 2.3.11 release on the WooCommerce site did include a mention of the security fix.

    Report


    1. Speaking as a newly minted .org theme author, I always include the changelog. It’s just good practice, and I was actually surprised to find that it’s not a theme requirement.

      Report


  6. BTW, I think we’d all appreciate it if those changelogs were written with users in mind. They don’t need to be detailed developer oriented lists. If you want those, use a changelog.txt file or something.

    Keep that readme short, made for users, and to the point. Helps. Under 10k in size, please. Purge old useless information.

    Report


    1. Do you think we could display them better or auto-trim so they don’t get too crazy?

      Report


      1. Spot on article and idea. It’s a friction point when developers have not updated properly. Concise information sells the upgrade with facts. Thanks Jeff Chandler for the article.

        Report


      2. Oh sure, we can absolutely do things like auto-trimming and cutting down sizes and purging stuff. That will fix internal issues with size, certainly. Already working on that. :)

        But nothing really beats writing your documentation with the end-user in mind. Even if we did something like purging old useless info and cutting down these things, that’s still an automated process. My point is that changelogs, along with everything else in the readme.txt, should really be written to be useful to the end-user. Developers can go look at the SVN or Git history for details, or you can detail those in a separate document like changelog.txt.

        Report


      3. I like the idea of the changelog.txt or changelog.md. Time to move all my ancient logs into that one for my plugins.

        I usually follow plugin releases with a post on my site to better explain the changes. Hopefully, users do take note when updating.

        Report


    2. I’ve often thought that having more requirements would be helpful – require an update notice of X length (if only we could detect developer-facing language), require a changelog entry for each tag and be able to display just that changelog for “more details” on an update than the shorter notice, that kind of thing.

      Report


    3. Gentlemen, Jeff argues rather compellingly here for more information. Giving publishers the benefit of the doubt and decent technical information seems the more civilised course. Those who can’t read detailed changelog information probably wouldn’t be reading changelogs in the first place.

      Report


  7. Updating the changelog before each release is actually my favorite part of pushing an update. It’s a nice way to summarize everything we’ve done this week, pat ourselves on the back, and communicate our progress to users.

    As the poll suggests, these things get read. When I want to make my users know about an important feature I’ll be sure to mention it there. It is a sure-fire way to reach a lot of people. I have no doubt our changelogs get read more than our blog. Which is totally fine….

    Report


  8. It should have standardized changelog to use by all the plugin creators, and I wish the changelog should always include date.

    Report


  9. I use a theme that uses one version number on the file download, another version number in the WP dashboard, and just dates in the changelog – no version numbers! I raised this with the developers but nothing changed.

    Report


  10. Two thumbs up for more descriptive plugin and theme changelogs, with security fixes front and center. When I read some plugin changelogs, I get the distinct impression that I’m reading a list of version control commit comments from programmers who don’t like writing version control commit comments.

    Report


  11. “705 out of 1,152 voters said they always read it while 338 people said they sometimes read it. ” – Total BS. 95% of my users do not even read basic instructions or even descriptions of plugins let alone the change logs. I do not believe these numbers for one second.

    Report


    1. It’s true that many of the respondents were developers, which probably biases the results a great deal.

      Report


  12. Playing devil’s advocate– do you suppose developers who don’t mention security vulnerabilities and/or fixes in their changelogs are deliberately doing so to avoid publicly acknowledging their product isn’t “perfect”? Or perhaps are being told to do so by their supervisors?

    Report


  13. Thanks for the post, Jeff, I completely agree with you. I always check the changelog before deciding if it’s worth updating a plugin or if it can wait. Agree with Joseph also about the addition of date of the change (in ISO format, please). Also, what bothers me is that some plugin authors do not add the changelog in reverse chronological order and you have to scroll down to look for the latest changes…

    Report


  14. This is so right on Jeff. It’s a lesson to learn for all developers though, not just plugin developers and it doesn’t always come easy (it took me a long time to get to this point in my own work).

    Report


  15. Jeff,
    You’re absolutely right. I’ve heard the argument that “users” don’t read them. As a developer, I almost always do, especially on ones that have a reputation that merits caution. I guess that means that we developers and site admins just don’t matter. [sniff!]

    I think that along with the basic problem, that writing documentation is boring and we hate to do it, there are other possible factors. Taking Woo as an example, I wonder if they keep it very bland so that people who read it won’t freak out, and bury their tech support, or worse, badmouth the plugin to others. Spin doctoring, as it were. “Mistakes were made….” ;)

    Report


  16. Nice one Jeff. I’ve always been a bit unsure about how to write changelog updates, or rather, who to write them for. Keeping them non-technical for users makes sense since devs can always be redirected to github or the trac log anyway.

    One thing I would LOVE to see is a changelog for themes. It’s kind of weird that themes don’t have a changelog on the repo like plugins, and theme updates include a link to a non-existent changelog. What is the point of the “view version X details” link? Better to remove it IMO until a changelog is added, or let me redirect to the changelog I maintain on my site that no one sees :)

    Report


  17. Thanks for sharing this Jeff. I’ve never seen anything wrong with the types of changelog you posted above. I guess that’s because I immediately know what the technical jargon means. Thanks for sharing an alternative (and important) view of things.

    Report


  18. YUP. I’ve tweeted and griped about bad changelogs for a while… There’s no standard really or ‘boilerplate’ and I don’t think it would be too hard to make one and get everybody to agree on it. Dates next to versions and item prefixes like “bug” or “feature” etc help. I read changelogs pretty much every single time for every plugin/theme or app on my phone too. If we set a standard most will follow it.

    https://twitter.com/ChuckReynolds/status/134050067614142464
    https://twitter.com/ChuckReynolds/status/384823150342438912
    https://twitter.com/ChuckReynolds/status/558438308624093184

    Report


  19. Great post ! I think we all could benefit from improving our changelogs.

    Report


  20. I’d veen wondering whether it couldn’t even be taken a step further & a standard form of formatting (a shouty caps lock prefix to the line perhaps stating ‘SECURITY FIX’?) a requirement, to make it absolutely clear for all users when one’s included. A formatting standard could potentially go further of course, to also have ‘Bug Fix’ & ‘New Feature’ prefixes, but the security fixes are by far the most important.

    Report


  21. I think adding the date (as first entry preferably) to the changelog is also a good idea

    Report


    1. +1 for this. It’s useful to know not only what was changed, but when. In fact, some plugin developers use the date in YYMMDD format as the version number, which I think is very efficient.

      Report


      1. I agree, I’ll have to start adding the date to my changelogs. However, I don’t think the date should ever be used as part of the version number. Ideally, semantic versioning should be used.

        Report


      2. I am guilty of this and I plan to revert to semantic versioning again (thanks for the link, I was looking for that).

        Ideally we can come to some sort of standard of adding the date in a specific format. For readability I would like to suggest to use as a first entry “date: YYYY.MM.DD”

        Report


      3. ISO date format is essential. Using local date formats defies logic.

        Report


  22. Couldn’t agree more. I feel the changelog is very important and invest considerable time each release making sure that ours are clear, concise, and readable and link to documentation and more info when warranted. In fact, I spent 5 hours last Monday going through all our pull requests and issues for the WP Migrate DB 0.7 / Pro 1.5 release and distilling it down into our changelogs. It’s very manual and tedious, but I think it’s worth it.

    Report


  23. I suspect that some plugin authors prefer to avoid the perceived negative PR that comes from stating that their plugins were vulnerable. However, many are sure to be caught out in the long run when site owners don’t bother to update their sites because they have not realised the risk.

    Report

Comments are closed.