Add Upgrade Notice for Themes

[afragen]

There is upgrade notice for plugins that displays on the core update page if $transient->upgrade_notice is set in the pre_set_site_transient_update_{plugins|themes} filter, but there is no corresponding upgrade notice used or available for themes.

I propose adding a similar usage for themes as currently exists for plugins.

Use case, when theme upgrades are pending a notice of what changes, etc. will be available from the main update page.

[afragen]

Any comments?

[costdev]

@afragen Can you drop some testing info so that the patch can be tested? Thanks!

Additional props: @pbiron

Updated PR for adding an upgrade notice to theme updates in update-core.php as there is for plugin updates.

Trac ticket: https://core.trac.wordpress.org/ticket/34986

[afragen]

You can test the PR with the following plugin code. Obviously this would need to be added by the theme dev.

<?php
/**
 * Plugin Name: Test #34986
 * Description: Testing Trac Ticket #34986
 * Author: WP Core Contributors
 * Version: 0.1
 */

add_filter( 'site_transient_update_themes', 'add_upgrade_notice_34986', 20, 1 );

function add_upgrade_notice_34986($transient){
    $theme_slug = 'twentytwentythree';
    if ( isset($transient->response[$theme_slug])){
        $transient->response[$theme_slug]['upgrade_notice'] = 'Test of upgrade notice, #34986.';
    }

    return $transient;
}

To test, decrease the local version number of the Twenty Twenty Three theme so that it shows an update.

[afragen]

Above is for testing. I'm pretty sure all the dev needs to do is add a section == Upgrade Notice == to their readme.txt for the specific update and the readme parser in dot org will add the data to the update transient.

[oglekler]

Patch (#comment:8) works as expected, screenshot is above.

We are in 9 days until the Beta 1, so, if this is going to trunk, it needs to move.

[afragen]

Corresponding ticket for plugins, #57939

[zunaid321]

Test Report

This report validates that the indicated patch addresses the issue.

Patch tested: ​https://patch-diff.githubusercontent.com/raw/WordPress/wordpress-develop/pull/4238.diff

Environment

• OS: Windows 11 (22H2)
• Web Server: nginx/1.23.4
• PHP: 7.4.33
• WordPress: 6.3-alpha-55505-src
• Browser: Chrome Version 114.0.5735.110 (Official Build) (64-bit)
• Theme: Twenty Twenty-Three

Testing Instructions

• Applied Patch
• Activated Attached Plugin - test-34986.zip
• Lowered the theme version of Twenty Twenty Three Theme
• ✅ The update notice showed up in the Updates Page for the Themes section.

Plugins Used

• Attached: test-34986.zip

Screenshots

• Update Notice - ​https://prnt.sc/RRfgI66PkY27

[peterwilsoncc]

I ​asked the meta folks in Slack if the themes upgrade API endpoint included an upgrade notice and was told it doesn't.

Apparently the API only includes data in the stylesheet headers.

I think there has been discussion in the past about introducing one but it's premature to include the feature in core until it exists. I'm going to bump this to a future release so any action can be coordinated with the meta team.

[afragen]

@peterwilsoncc you're looking in the wrong place. Neither plugins or themes has this data from the API. The data exists as parsed data from the readme.txt file from the parser where it is included in the update data if it exists.

[dd32]

This would be pending ​https://meta.trac.wordpress.org/ticket/215 as readme.txt is not parsed for themes at all on WordPress.org. There's unlikely to be any movement on that (IMHO) until the Theme Directory is redesigned to accomodate it.

you're looking in the wrong place. Neither plugins or themes has this data from the API.

Plugins do offer this data via the API.

[afragen]

Dion why are these or any of the APIs private. It makes things like this very difficult.

[peterwilsoncc]

The transient filter for testing in comment 9 shows the displayed data is intended to come from the API. If the theme update API adds support for upgrade notices then I'll happily add this feature to core, otherwise the code will go unused.

[dd32]

Replying to afragen:

Dion why are these or any of the APIs private. It makes things like this very difficult.

While it's not ideal it's private (There's no reason AFAIK, other than the breakage that would happen during migrating of it), there's nothing in there that's related to this ticket.

The fields are not parsed/stored/touched by the Theme Directory code-base, which is open-source. In the event it's added there, it's literally a 1 line addition to the update-check API to fetch that meta_value field too.

[SirLouen]

I can see that thare are multiple test reports, but this is not progressing because of some Meta limitations for now. Since there is nothing to test, removing needs-testing tag.

[joostdekeijzer]

Hi,

Based on the "Update URI" functionality for themes I'm developing an update solution for my clients custom themes and plugins.

It would be very helpful if I could use the upgrade_notice field not only for plugins but also for themes.

Can't PR ​https://github.com/WordPress/wordpress-develop/pull/4238 be applied and have the Meta team have their own planning?

The code won't be unused as it may be used by external developers like myself.

PS
Sorry for the spam. I did not know github comments are included here...

Hi Peter,

A couple of notes inline.

However, I can't see any indication of the upgrade_notice being supported for themes on the themes page or network themes page.

As I suggested in the Trac ticket: since there also is the "Update URI" functionality for themes it may be used by external developers like myself 😄

[peterwilsoncc]

Replying to joostdekeijzer:

Based on the "Update URI" functionality for themes I'm developing an update solution for my clients custom themes and plugins.

It would be very helpful if I could use the upgrade_notice field not only for plugins but also for themes.

Can't PR ​https://github.com/WordPress/wordpress-develop/pull/4238 be applied and have the Meta team have their own planning?

The order needs to go something like this:

1. Theme Readme.txt spec supports Upgrade Notices (✅ -- have for quite a while)
2. Meta team agrees on an endpoint structure for including the data
3. Meta team plans to implement
4. WordPress Core adds support for the endpoint value; Meta implement

The reason being that if something is added in WordPress Core prior to discussing the feature with the meta team; we committers would be making assumptions about the meta code base that we're unable to see.

The chances are that the field would end up being upgrade_notice but we still need to build the roads before attempting to use them.

PS
Sorry for the spam. I did not know github comments are included here...

No need to say sorry, even people who use trac daily sometimes get caught out by integration rules. Trust me, I know ;)

[joostdekeijzer]

Ok, I can follow that. But that does seem to put this minor change "on hold" for unknown time.

Regarding "building roads": developers using the UpdateURI field like myself may already have roads. In my API endpoint the upgrade_notice field is populated for both themes and plugins and when I apply the changes by Andy it works fine and as I would expect.

But following your steps: is the meta team aware of this (and perhaps other tickets)? Apart from ​https://meta.trac.wordpress.org/ticket/215 I could not find any open tickets referencing upgrade_notice or readme.txt. Their ticket ​https://meta.trac.wordpress.org/ticket/6897 was closed as invalid.

I really do hope it's possible to apply Andy's patch for the "3rd party" roads that external developers may have build.

[joostdekeijzer]

For those interested, a workaround below using javascript/jQuery

<?php
add_action( 'core_upgrade_preamble', function() {
  // !!! Currently WordPress does not support upgrade_notice for themes
  $themes = [];
  foreach ( get_theme_updates() as $stylesheet => $theme ) {
    if ( ! empty( $theme->update['upgrade_notice'] ) ) {
      $themes[ $stylesheet ] = wp_strip_all_tags( $theme->update['upgrade_notice'] );
    }
  }
  if ( ! empty( $themes ) ) {
    printf( '<script type="text/javascript">jQuery( function($) { $.each( %s, function( index, value ) { $( "#update-themes-table input[type=checkbox][value=" + index + "]" ).closest( "tr" ).find( "td.plugin-title p" ).append( "<br />" + value ); } ); } );</script>', json_encode( $themes, JSON_FORCE_OBJECT ) );
  }
} );