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 responses to “WordPress Plugin Developers Need to Communicate Better in Change Logs”

  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!

  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!

  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.

  4. 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.

  5. 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.

  6. 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….

  7. 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.

  8. 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.

  9. “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.

  10. 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…

  11. 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….” ;)

  12. 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 :)

  13. 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.

  14. 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.


  15. 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.

  16. 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.

  17. 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.


Subscribe Via Email

Enter your email address to subscribe to this blog and receive notifications of new posts by email.

%d bloggers like this: