Do WordPress.org Themes Need a Changelog?

photo credit: time – (license)

Over the weekend, Theme Review Team member Jose Castaneda posted a proposal to add change logs to themes hosted on WordPress.org. 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 WordPress.org 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 WordPress.org 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 make.wordpress.org/themes 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.