WordPress.org

Make WordPress Core

Opened 7 years ago

Closed 7 years ago

#31074 closed enhancement (fixed)

Twenty* themes should have an official change log

Reported by: jgehrcke Owned by:
Milestone: 4.3 Priority: normal
Severity: normal Version:
Component: Bundled Theme Keywords:
Focuses: Cc:

Description

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

Attachments (1)

31074.patch (8.6 KB) - added by mercime 7 years ago.
Patch for changelogs for the Twenty Fifteen and Twenty Fourteen themes

Download all attachments as: .zip

Change History (18)

#1 @SergeyBiryukov
7 years ago

  • Component changed from Themes to Bundled Theme

#2 @lancewillett
7 years ago

  • Keywords 2nd-opinion added
  • Milestone changed from Awaiting Review to Future Release

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.

This ticket was mentioned in Slack in #core-themes by lancewillett. View the logs.


7 years ago

#4 @hays7
7 years ago

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

  1. 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


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).

Version 0, edited 7 years ago by hays7 (next)

#5 @lancewillett
7 years ago

  • Keywords needs-patch added; 2nd-opinion removed

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

#6 @mercime
7 years ago

@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)?

#7 @lancewillett
7 years ago

Both, please. :)

#8 @mercime
7 years ago

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
7 years ago

Patch for changelogs for the Twenty Fifteen and Twenty Fourteen themes

#9 @lancewillett
7 years ago

  • Keywords has-patch added; needs-patch removed

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.

#10 follow-up: @mercime
7 years ago

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.

#11 in reply to: ↑ 10 @DrewAPicture
7 years ago

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

#12 @mercime
7 years ago

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

#14 follow-up: @mercime
7 years ago

@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

#15 in reply to: ↑ 14 @lancewillett
7 years ago

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.

#16 @lancewillett
7 years ago

  • Keywords has-patch removed
  • Milestone changed from Future Release to 4.3

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.

#17 @lancewillett
7 years ago

  • Resolution set to fixed
  • Status changed from new to closed
Note: See TracTickets for help on using tickets.