Anatomy of a Quality Changelog: Helping Your Users

Screen-Shot-2016-02-10-at-9.43.40-AM

Every Tuesday, Maintainn does routine plugin updates for our customers. This is one of the services we offer, and one reason they sign up for our services in the first place. They know a WordPress professional is available to keep their site up-to-date and secure.

Because of this schedule, we read a lot of changelogs every week. We need to see what has changed in your plugin so we can update without issue. Some changelogs are well done and do a good job providing the necessary information, while others are not always so good, which makes it difficult to update with absolute confidence.

I am going to go through what I feel helps make a quality changelog. Here’s a little bit on how to create a changelog that will instill confidence in users so they can apply your new update without fear. These are not requirements by any means, but something to consider:

When the plugin received an update

Providing the date that the plugin received an update can aid site developers. They will be able to see how active the plugin is in development. This can be valuable information for decision making about whether to seek alternatives that are current with the latest version of WordPress. If your plugin has not been updated in a few years, there is chance that security concerns have emerged. Parts of WordPress or another plugin that yours relies on may have changed as well, causing it not to work like expected. Knowing when updates go out helps your users make smart decisions for their site.

Enhancement vs bug fix vs security fix

Listing the type of change involved for each item can help provide more information to your user. If they see that there is a security fix in the latest version, they may update right away. If there is a bug fix available for a problem they have been experiencing, they will smile with joy. They will know you are taking care of them and paying attention to their concerns. Perhaps you have received a lot of requests for certain functionality that will help them. If you let them know in a clear way that that is now available, they may love you forever. Make it easy for them to know what is coming their way.

On top of providing the type of change, organize the list of changes by the type they are. Your changelog will be easier to consume if you group security and bug fixes together. Afterwards, you can list enhancements.

Perhaps you have also made a pro or premium extension for your plugin. If some changes are exclusive to those extensions, let the users know which.

If you know there is a good chance of breaking sites, let your users know. I cannot guarantee they all will read notices, but that doesn’t mean you shouldn’t at least try to communicate what’s going on from your end. One way you could do this is posting a message at the top of the changelog list, or you could use the “upgrade notice” area of the WordPress.org readme.txt file. You can also try to quell potential issues by posting a sticky thread on the plugin’s support forum. Last, if you have any sort of social media strength for the plugin, let your followers know it is coming.

Versioning

There are many systems for versioning code. One of the most popular is Semantic Versioning, or SemVer for short. With SemVer, each release has a three digit version, and each digit relates to a certain type of update. Your first major release is version 1.0.0. Any version before that is beta for the initial launch. With that version, you would consider each digit as the following: Major.Minor.Patch. There was also a recent article suggesting to view the version as Breaking.Feature.Fix.

The first digit will only increment if users should proceed with caution before upgrading. The second digit increments when adding new features that should not break current functionality. Finally, the third digit is for quick bug fixes that do not add but do correct current functionality. Often this digit is for security fixes or bugs that cannot wait for the next minor or feature release.

Observant WordPress plugin developers will note that WordPress itself does not follow Semantic Versioning. While it does use the third digit for bug fixes, it combines the first two digits as the current version. We do not say WordPress is on “version 4” and there was four major releases. We say it is on “version 4.2 ” and has had 28 major releases.

Regardless versioning scheme chosen for your plugin, make it it consistent so changes are easily parseable.

Make the changelog easy to locate

Keeping changelogs from many locations up-to-date and accurate can be time-consuming and cumbersome. I am aware of that as a plugin developer myself. Making the changelog up front and easy to find right away still makes our job easier. The WordPress admin provides a link to view the latest changes when updating plugins. The information gets displayed in a modal popup, and provides it all right away. At least for me, it gets frustrating to see a link to some external website that I need to visit just to see new changes. This means at least two extra clicks, need to locate the changes in the new tab, and need to close the tab. If one has a lot of plugins to get through and update, these extra actions add up.

Once again, this is not a list of required details to consider for your changelog. It is also not a definitive list, as I likely missed good ideas that others have thought of–just a few suggestions that may help you create better changelogs that communicate with your users most effectively. What else would you appreciate in a changelog? Tell me in the comments and let’s talk about it!

Read more articles in ,

1 thought on “Anatomy of a Quality Changelog: Helping Your Users”

  1. I wish all the changelogs were written properly!
    An annoying thing for me are the changelogs of premium plugins, when the link is pointing to the WordPress Plugin repository but gives 404…

    Cheers

Leave a Comment

Your email address will not be published. Required fields are marked *

Scroll to Top