Twenty* themes should have an official change log

[jgehrcke]

Currently, the TwentyXXX theme updates do not provide proper release notes. In particular, updates are offered via the dashboard, without a simple method to see what actually changed. The lack of semantic versioning or a guarantee for not breaking backwards compatibility complicates the situation.

I think that most of us agree that there is plenty reason why proper release notes / a change log are helpful and sometimes required and hopefully you agree that this is not the place to list all of these arguments. Proper release notes are state-of-the-art in any serious open source software project, and the WordPress core is no exception, which is great. However, the TwentyXXX theme releases seem to be a little neglected in this regard.

Although I ranted about this topic elsewhere [1] and Samuel Wood clarified in the forums [2] that this is something that is being worked on, I think that it is good to have a central place (this ticket) to refer to, at least for the community, but hopefully also for internal use.

I want to add that others discussed this topic in the forums, too [3], and these are all valid quotes, in my opinion:

"Updating from 1.1 has caused some minor, but unexpected presentation changes on one of my child themes, and I'd like to know what else has changed and what to test for"

"I really expected something more accessible documenting revisions to a theme that has had over 200,000 downloads."

"what was the point upgrading this one? -- Good question. Without the release notes it is difficult to say what you might be missing out on."

References:

[1] ​http://gehrcke.de/2015/01/official-wordpress-themes-should-have-an-official-changelog/

[2] ​https://wordpress.org/support/topic/opinions-please-official-wordpress-themes-should-have-an-official-change-log-1

[3] ​https://wordpress.org/support/topic/twenty-twelve-12-release-notes

[lancewillett]

Thanks for the ticket -- I think it's worth discussing more, pros and cons. One more thing to maintain as part of the theme, yet is very useful to authors updating to new versions.

[hays7]

Two suggestions on how to easily get automated changelogs:

1. Use the github history for the folder of the theme:

​https://github.com/WordPress/WordPress/commits/master/wp-content/themes/twentyfourteen

2. Use the trac view of the changes:

https://core.trac.wordpress.org/log/trunk/src/wp-content/themes/twentythirteen?verbose=on&format=changelog&stop_rev=&limit=100&mode=stop_on_copy

(You can get it by using the ChangeLog link at the bottom of pages like https://core.trac.wordpress.org/log/trunk/src/wp-content/themes/twentythirteen/?action=stop_on_copy&mode=stop_on_copy&rev=31848&stop_rev=&limit=100&verbose=on&sfp_email=&sfph_mail= )

---

To build a physical changelog.txt you'd simply need to copy-paste the changes between the two commit IDs (old theme release vs new one).

[lancewillett]

Let's do this. See also #31814 for adding README files.

[mercime]

@lancewillet Interested in helping out. What format would you like the changelogs in? CHANGELOG.txt in each of bundled themes or a Codex page for each of the themes (just like WP changelog in Codex - per release)?

[lancewillett]

Both, please. :)

• Text files: text format, using the ​WordPress plugin format as a guideline.
• Codex: only ​Twenty Fourteen has one right now, I think.

[mercime]

Attached patch is first pass at the changelogs for the Twenty Fifteen and Twenty Fourteen themes. Please disregard the ticket numbers I added as I originally prepared for the codex edition.

I would like to propose the following:

• Create a Codex Page listing all the Twenty-* themes - with a short description and links to the individual pages of each theme as well as the changelog pages of each theme.
• Each theme's new Codex page will show information about the theme including customization like the Codex page of Twenty Fourteen. Under that, add a table/list similar to ​https://wordpress.org/download/release-archive/ which contains contain release dates, link to the themes' download pages, plus links to the changelog page/s, etc. I already researched and compiled the release dates of each theme.
• Each theme's changelog page will contain the logs like in attached patch and can be verbose in addition to the links to the trac tickets to show them the actual changes.
• Since there's changelog page in the Codex for respective themes, instead of adding a CHANGELOG.txt files for each of the themes, we add the links to the Codex changelog pages in the respective readme.txt files e.g. ​https://wordpress.org/plugins/buddypress/changelog/

Having said that, if the preference is to add CHANGELOG.txt as well in respective theme folders, no problem.

[mercime]

Patch for changelogs for the Twenty Fifteen and Twenty Fourteen themes

[lancewillett]

This is superb! Very cool. Love all your ideas, especially linking to the changelog in the Codex rather than bundling that in the theme itself — that's smart and reduces the need to update the theme just to change a typo or ticket link in the changelog.

I agree that we should link to these relevant pages and changelogs from the readme.txt file; see #31814.

[mercime]

Thank you @lancewillett :) Made two pages in the codex but they're not showing up yet as I think a codex admin needs to approve it first. I have to follow up on that because I have most of the materials ready for publication. I am also working on the readme.txt files.

[DrewAPicture]

Replying to mercime:

Thank you @lancewillett :) Made two pages in the codex but they're not showing up yet as I think a codex admin needs to approve it first. I have to follow up on that because I have most of the materials ready for publication. I am also working on the readme.txt files.

​http://codex.wordpress.org/WordPress_Default_Themes
​http://codex.wordpress.org/Twenty_Ten_Theme_Changelog

[mercime]

Thank you @DrewAPicture. This is to request for the publication of the following changelog pages as well:
User:Mercime/Twenty Eleven Theme Changelog
User:Mercime/Twenty Twelve Theme Changelog
User:Mercime/Twenty Thirteen Theme Changelog
User:Mercime/Twenty Fourteen Theme Changelog
User:Mercime/Twenty Fifteen Theme Changelog

[DrewAPicture]

• ​http://codex.wordpress.org/Twenty_Eleven_Theme_Changelog
• ​http://codex.wordpress.org/Twenty_Twelve_Theme_Changelog
• ​http://codex.wordpress.org/Twenty_Thirteen_Theme_Changelog
• ​http://codex.wordpress.org/Twenty_Fourteen_Theme_Changelog
• ​http://codex.wordpress.org/Twenty_Fifteen_Theme_Changelog

[mercime]

@lancewillet I found out that there's also a ​Twenty Fifteen page in the codex as well. But I think only codex admins can add information to the codex page before or after the sections of a page.

@DrewAPicture thank you once again. Should we just post here the general info to be added at the beginning of the Twenty Fifteen and Twenty Fourteen codex pages? Thinking of moving/organizing e.g. the FAQ from the current Twenty Fifteen ​readme.txt along with other info to the codex page.

In the meantime, have uploaded first pass of readme.txt files of Bundled themes in #31814

[lancewillett]

Replying to mercime:

@lancewillet I found out that there's also a ​Twenty Fifteen page in the codex as well. But I think only codex admins can add information to the codex page before or after the sections of a page.

Can we link to that page from ​http://codex.wordpress.org/WordPress_Default_Themes?

Thinking of moving/organizing e.g. the FAQ from the current Twenty Fifteen ​readme.txt along with other info to the codex page.

I think that's a good idea; consistent with the other themes.

[lancewillett]

Really nice work, mercime. For Twenty Sixteen we'll need to remember to create the changelog page on the Codex and link to it from the theme's readme.txt file.