40 Comments

  1. Mizagorn

    With you 100% on this one, Jeff. Good post.

    Report

  2. Marcus L Tibesar

    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

  3. Frank Corso

    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

  4. devinwalker

    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

  5. bunkerboy

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

    Report

  6. J.D. Grimes

    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

  7. Peter Cralen (@PeterCralen)

    Theme’s authors too please ;)

    Report

    • Paul

      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

  8. Otto

    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

    • Matt

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

      Report

    • Helen Hou-Sandi

      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

    • Alec

      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

  9. Jason Lemieux

    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

  10. Joseph

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

    Report

  11. Geoff

    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

  12. trevellyan

    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

  13. enfocusauctions

    “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

  14. Andrew Mills (@mrandrewmills)

    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

  15. stefanodotta

    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

  16. Chris Wiegman

    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

  17. Dave Chu

    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

  18. Ben Sibley

    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

  19. Ryan Hellyer

    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

  20. Chuck Reynolds

    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

  21. Basha4SEO

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

    Report

  22. Geoff at Web Propelled

    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

  23. Piet

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

    Report

  24. Brad Touesnard

    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

  25. Martin Jarvis

    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.

%d bloggers like this: