WordPress Plugin Developers Need to Communicate Better in Change Logs

photo credit: elycefeliz – cc

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.