What Lawn Care Taught Me About Why You Should Read Changelogs

You might want to communicate better with the yard care pro. Creative Commons Image Attribution — You might want to communicate better with the yard care pro.
Creative Commons Image Attribution

My neighbors pay someone to cut their grass. As far as I can tell from being an only-mildly-nosy neighbor, here’s how the weekly-ish transaction goes:

Yard guy (we’ll call him Pete) shows up to mow the whole lawn. Right before he starts, Pete walks up to a cushioned chair on the front porch, and picks up his check from under the cushion.

Every now and again—but by no means on each transaction—there is a brief interaction between Pete and the lady of the house, who works from home. We’ll call her Julie.

Here’s where I am going to stretch an analogy to make my point: imagine that the only correspondence between Julie and Pete happens under that cushion, and is always initiated by Pete. In our hypothetical world, there’s no other way for Julie to communicate with Pete.

Now, further imagine that Julie has made some changes to her lawn and needs to communicate with Pete. How important does that envelope become?

You have just underscored the use of changelogs for WordPress developers.

The changelog is the only shot I have at communicating things to my users. If I make a change that affects everyone running a certain version of PHP, for example, there’s no way other than the changelogs to get that message out to folks.

I’m not overdramatizing things here: there is no mechanism for contacting users of my plugins.

There is no (other) mechanism for WordPress plugin devs to communicate with users. Read changelogs. Click To TweetMy best case scenario is that when a user installs my plugin they opt in to my newsletters on the settings page of that plugin. But with over 10,000 plugin active users on one plugin and 7,000 active users on another, I can assure you my opt-in rate is well below 1%. When someone installs and activates my plugin, the odds are overwhelming that the next “interaction” I have with them is when they click “update” in a few weeks on that plugin.

On top of that, even if a user does opt in on that settings page, my current system is painfully unsophisticated: I have one list for all subscribers. That list is not designed to be a means of communicating with existing plugin users. It’s designed (as I mention on my home page at least twice and every other chance I get) to educate.

Thankfully I’ve never had a breaking change with any of my plugins. If I did, though, my only option would be to stuff a lengthy explanation under the cushion and hope that you read it before you started mowing the lawn, Pete.

That’s one of the reasons I try to make my changelogs fun.

My plugin changelogs should not be ignored. https://t.co/Nd6Ei3Vomx With a shoutout to my overtagging past. pic.twitter.com/LTUlTsn3mR

— Ben Meredith @benunc@fosstodon.org (@benUNC) March 6, 2016

My thought is that if I make them interesting enough, more people will read them. And that means that holds hand over heart you’ll never see “Various Bug Fixes” on my changelogs.

Here’s a brief list of things developers can write in their changelogs in order of effectiveness from most to least: