Do Themes Need a Changelog?

photo credit: time - (license)
photo credit: time(license)

Over the weekend, Theme Review Team member Jose Castaneda posted a proposal to add change logs to themes hosted on The discussion has been on the table for years, but renewed interest in change logs is surfacing for the upcoming 4.3 and 4.4 release cycles.

Adding changelogs to themes requires action on two related tickets: a meta ticket to add support for change logs on and a core ticket to expose the changelog file to users in the WordPress admin.

Castaneda’s proposal requests that the team select a standard format for theme authors to follow in either the readme.txt file or a new changelog.txt file. From there the team would follow the core development release cycle to complete whatever steps necessary to get changelog support added to themes.

Theme Review Team members are divided on whether or not change logs are beneficial to users, as they already have the ability to detect changes using a .diff file when authors submit updates. Others find change logs to be a more readable addition.

“Personally, I find change logs to be incredibly helpful, even when using a .diff,” Theme Review Team admin Chip Bennett said. “The changelog is the human-readable summary of changes, that can really help grok the diff changes.”

Justin Tadlock isn’t convinced that WordPress users would benefit from themes including change logs:

Honestly, I don’t see change logs as all that important from a user standpoint. While I don’t have any official stats, I’d wager that the vast majority of users don’t read change logs and, of those who do happen upon one, don’t understand most of what’s actually in the file.

Change logs are, by and large, a developer tool. It’s a nice-to-have feature. I don’t care one way or another. I never read them. I doubt we’ll get great change logs from the majority of theme authors. We can’t even manage to get some semantic versioning down or basic inline PHP docs. We’ll probably see a lot of Git commit logs copied/pasted or my personal favorite, “Changed a bunch of stuff. Too busy building awesome s*** to care about tracking changes”.

Active discussion on the topic is taking place on the blog. If the team concludes that change logs are beneficial, the main question to answer is whether or not they should simply take up residence in the readme.txt file, like plugins do, or have their own separate file.

Ultimately, the issue boils down to whether or not WordPress users read and appreciate changelogs, or if they are more beneficial for developers. As the Theme Review Team is primarily made up of developers, it would be valuable if average users who desire theme change logs could chime in on situations where the file might be helpful.


44 responses to “Do Themes Need a Changelog?”

  1. I would LOVE changelogs.

    I build my own themes so this doesn’t affect me personally but I also host sites for my clients, and those clients may use free themes. I perform updates for my clients and I hate not knowing what has changed in the theme. My client may not care, but as a developer/maintainer, it would be really useful for me to know what’s going on and what this update is actually doing.

  2. I would suggest Justin is right: many WordPress developers are such sloppy skateboard kids that his parody comment would come true. On the other hand, automatically generated diff logs by default with space for explanatioin would be very helpful.

    Thanks for letting us know about this discussion.

  3. Justin Tadlock says: ” Changelogs are largely develop tools…” honestly, Themes are developer tools as well, and when you manage many many websites with many different themes on them, you want to know whether they are updated with important security updates or just adding ads into the options page. Changelogs are best practice for code. I honestly can’t think of one reason to ignore them completely that is justifiable.

  4. Users don’t look at plugin changelog’s either but I can’t picture anyone in the community saying they are unnecessary for that reason.

    Are changelog developer facing? Absolutely. Does that mean themes shouldn’t bother with them? Absolutely not.

  5. The lack of any description of what has changed when a theme is ‘updated’ is a strong disincentive to update – If there’s no description of what has changed in the theme why would I spend time changing it and potentially having to undo the change because I don’t like the changes?

  6. Arf, Arf, Arf, Arf, Arf !

    I give 5 out of 5 barks FOR mandatory theme changelogs.

    Let the Lowest Common Denominator WordPress users get their websites up-and-running from WordPress dot com, where the least amount of setup thought is required. WordPress dot org users go there because they want more control over their individual websites. Let them have it.

  7. I don’t think I was clear with my joking comment, especially when not in the context of previous discussions. I just don’t think change logs in their current format hidden away in the theme folder serve much purpose for the average WP user. TRT’s primary focus is centered on users. Everything we do starts there. Now, you add in support for displaying change logs prior to theme update directly into core, it’s a whole different matter. We have something that’s useful, informative, and fits into our primary focus.

    We’ve been asking for a similar readme standard for themes (like plugins) for years, which would have included change logs. The primary ticket for change logs has been sitting there for the last 16 months. The ticket for the readme standard has been stale for 18 months.

    Maybe TRT should pioneer this standard. I’d rather see some movement in core first. Maybe this discussion will kick-start that movement. We probably need TRT and some of the core leads communicating.

  8. Why does it seem so many WordPress devs argue that users are either too lazy or too stupid to take advantage of information about products they use? Gets on my nerves, seriously.

    Yes, changelogs are important, vitally. Yes, people who merely maintain sites use them all the time as reviews prior to pretesting an update. I have paid programming interns that do just that who are not quite yet engineers, but learn through maintainenance and support. We mentor them on the process, which includes prioritization of updating client sites. And that starts with changelogs.

    And yes, mere mortal users also check changelogs. Maybe not with the frequency of other groups, but that’s not the point. Please, when did WordPress devs become such snobs?

  9. Changelogs should be required by all developers. The main issue is that users are not able to get any insight other than trial and error unless a developer provides a changelog.

    Frankly, every developer should have a changelog for their themes, and plugins.

  10. Wherever there is code a changelog should be in place. NOT for things such as layouts, styles etc. Thats simply ridiculous unless VERY brief.

    For example “Added 16 CSS classes” is fine. Dont need define each one and what they do. Added “3 column Layout” fine.

    Fixed this/that in code. Fine.

    In other words, a brief synopsis of updates. Especially given that the TMT is working to get away from getting function per se away from themes.

  11. I believe a Change Log should be part of the theme package because it’s like software, every change should be noted, especially for those who do check them out. There’s also instances where a web designer or webmaster is managing a client’s website; should there be an update, it’s important to see what changes were made.

    I’ve also seen themes get radical changes, so it wold be nice to know what was changed. As one who designs and develops WordPress themes, I like to include a changelog, in both my free (at and commercial themes.

    For the most part, the average user of themes from the repository probably does not read or even realize there’s a change log, but again, there are some who know it and read them.

  12. Yes, we’ll get there. My goal is to get them working with a full readme, not just a changelog. Easier in the long run to unify things. But, there are structural differences and we also must solve existing problems before tackling new ones. Slow, and annoying. I know. I agree. Small steps leading to big steps.

  13. The need more than a changelog, they need some semblance of version control as well. My feeling is that theme version numbers should be matched to the highest wordpress version that they actively support (ie, have been tested for). So most themes now should be 4.2.xxxxx, where the .xxxxx incremental is the only part of the version number controlled by the developer. The rest should be automated in some manner. Perhaps even tie the version number to a changelog system, where the developer explains the change and wordpress assigns the version number to match.

    It would make it much easier to search through themes to find the ones that are actually updated and current, and not out of date. So many themes are just not maintained.

  14. Simply put, if you are serious working with WP for your customers, then you MUST know what are you installing or modifying every time an update is applied.

    And yes, themes should also show a visible link to the changelog. Even more, themes should also show the its last update full date to allow you to determine if that theme is so old that could be obsolete and hence break your site.

  15. Haha, whuuuut? Only in WordPressland would people actually question the value of changelogs. Are people seriously suggesting that a diff is an adequate replacement? Seriously?

    Here’s an idea — instead of getting bogged down in terms of whether people would use them or not, or use them properly, or whatever, how about let’s just build the functionality in and if people use them, they do?

    And if you’re worried people are going to be shitty developers and not use the facilities available to document their code and inform their users — maybe that has something to do with the fact there are practically no processes within the WordPress community for cultivating good open source developers and the whole development is experience seems stuck in about 2006? Maybe if the plugin submission process was a little bit more than a lint and a rubberstamp, maybe people would be more invested in their projects and might take the time to do things like fill out changelogs?

    I’m getting off topic — yes, ffs; changelogs!

  16. Part of me is amazed this conversation has to take place because I see multiple marketplaces thriving which are focused on complex themes and plugins and all of them provide changelogs for both themes and plugins.

    The other part of me knows that the only people who seem to still believe users of WordPress aren’t smart enough to know or have the desire to have anything other than pre-configured software to make a website easily are the developers of WordPress and their teams. And therefore, they need to be educated as to what the current trends are.

    I don’t know about most of the people here, but I look through a lot of plugins regularly and based on the usage of those plugins there are many, many people downloading plugins with complex settings areas. Of course, the arrangement isn’t the same for themes so there isn’t the same information available for them. But seeing the market place platforms selling loads of themes, I would venture to say the trend is the same for themes as well.

    I know a lot of “developers” who started developing because they weren’t satisfied with the little bit of control and flexibility of WordPress for their own projects. That goes for themes as well as plugins. With over 37,000 plugins along side of a lot of themes (the number isn’t readily available on WordPress due to the different structure of the themes area) changelogs are vitally important.

    Maybe some day the WordPress team will accept the fact that their beliefs about users needs to change quite a bit. We aren’t the same group they started out with. We want to know and we need to know what is being changed in themes to help us know what potential issues we might face when there is an update without having to run comparisons through diffmerg to find out. Not all updates are equal. Changelogs are vitally important for many reasons.

    IMHO, WordPress repository for themes is one of the weakest links in the project. Themes hosted on need to be handled the same way plugins are handled.

    I find the comments coming from WP team members to be both irritating and arrogant. Listen to the users for a change.. log.. You aren’t as unique as you used to be.

  17. Yes! I always check changelogs and I know lots of others that do too.

    Love them or hate them, changelogs are the most user friendly approach. People want to know “what’s been changed?” and “will it break my stuff?”

  18. I would absolutely love to see changelogs for theme updates – I don’t know how this isn’t a thing already! Just so long as the changelogs didn’t contain something like “1. Security fixes” and that’s it. What a waste of time that is.

    • Just so long as the changelogs didn’t contain something like “1. Security fixes” and that’s it. What a waste of time that is.

      Good point, Joe. Apple almost single handedly (okay with a little bit of help from Microsoft) has made changelogs completely useless.

      The changelogs should contain a detailed diff file and require notes from the developer on each groups of changes made. The diff bit could then be folded in for the changelog (to make it shorter) but with the possibility of folding the code back out.

      Anything less and we’ll get the nonsense Joe feared. Changelogs which don’t tell us anything.

  19. Theme Updates vs Changelogs vs Unneeded Plugins:

    What if a Theme’s developer adds functions or features to his/her product that end users previously had to install a plugin to facilitate?

    If Easy Access to a Changelog doesn’t exist, the end user may continue to use an unnecessary plugin unaware that the theme itself now provides the desired function or feature.

    The end result may be plugin conflict with the updated Theme, or just duplication of code.

  20. In my view a changelog is so fundamental there shouldn’t even be a debate on whether or not one is needed. We’re talking software behaviour here and I, for one, want a heads-up on what impact an update may have before it happens.

    I check plugin changelogs beforehand and this has saved me from several embarrassing moments and at least one critical event. Not so with themes unfortunately :o(

    I remain frustrated that this basic document management tool is not present for themes. I have resorted to running fully-functioning and up to date localhost sites in parallel with those online, so I can update themes in a managed environment first, and get to the changelog before updating for real.


Subscribe Via Email

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

%d bloggers like this: