WordPress Theme Review Team Recommends Authors Start Keeping a Change Log

photo credit: Green Chameleon
photo credit: Green Chameleon

Last April, WordPress Theme Review Team member Jose Castaneda proposed that the team adopt a standard change log format. Theme authors are not yet required to keep a change log but the general consensus is that it’s a good practice that benefits users.

Castaneda revived the topic of change logs during the team’s most recent meeting, saying he hopes this will be the year that they can finally standardize the readme.txt file and take action on the change log-related trac tickets. This would require action on a meta trac ticket to add change logs to the WordPress.org theme listing tabs and a core ticket that would expose the change log to users in the WordPress admin.

Castaneda posted some basic recommendations as a first step towards educating theme authors on the proper format for writing a change log:

  • Listing versions in reverse-chronological order (newest on top)
  • One sub-section per version
  • Group changes made per version
  • Don’t dump commit logs (if using version control)
  • Emphasize deprecations

Even though a change log is not yet exposed in wp-admin, theme authors can still write one for users who are willing to do a bit of looking before updating. It’s especially important for things like changes to CSS selectors, the removal or addition of features, and anything that might cause child themes to break.

The theme review team is currently focused on fixing its review process, so pursuing the necessary tickets for a change log is not a pressing item on the agenda. When the team gets time to follow through on making change logs happen for WordPress.org themes, authors who already have one in place will be positioned to display them to their users.


8 responses to “WordPress Theme Review Team Recommends Authors Start Keeping a Change Log”

  1. OK, I am not a developer, so I guess I often ask the kind of questions developers think are stupid and irrelevant, because they don’t appear to be asking them.

    This is such a case, I think, so please forgive my ignorance. I don’t have an axe to grind. I am just trying to learn.

    Wouldn’t the wholesale adoption of a plugin framework like Herbert resolve this kind of issue?

    And OK, Herbert may be a little OTT for most people’s needs, but what about adopting WordPress Plugin Boilerplate as a minimum?

    It seems to me there is way to make things more transparent and less arbitrary, if the repository was a little more prescriptive about imposing a minimum standard for submission.

    Not only could that standard be open sourced, so that everyone who has a stake has input, but it would also make the job gatekeeper much easier.

    i.e. “So solly. No ticky, no laundly”.

  2. Just reading again what I wrote, I don’t think I made my point very clearly.

    What maybe I should have asked could have been something like …

    … would the adoption of Herbert/WPB-like framework, but specifically for themes, as an appropriate standard ~ and a basic submission low-hurdle ~ resolve this kind of problem, and possibly some others, including the workload of those who have the job of take care of the repository?

    • I recommend theme authors to look at _s

      I have seen an improvement in themes of those who use the starter theme. I easily recognise the changes the developer has made as that is where the issues are.

      Requiring theme developers to one starter theme or framework is like requiring all writers to use the same template.

      The way forward to to automate the process as much as possible and educate the developers to submit better themes code wise.

      • I was really only addressing the issue of the changelog format, which should be a much easier change to inculcate.

        I take your point and maybe its just as simple as pointing to a reference theme and suggesting they follow that example.

        However, I was trying to introduce a how hurdle which was in effect a go/no-go gate, and save those who manage the repositories having to waste their time with poor submissions.


Subscribe Via Email

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

%d bloggers like this: