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.