Make WordPress Core

Opened 17 months ago

Last modified 5 weeks ago

#51126 reviewing enhancement

Document the update offer parameter for auto updates

Reported by: johnbillion Owned by: desrosj
Milestone: 6.0 Priority: normal
Severity: normal Version:
Component: Upgrade/Install Keywords: has-patch needs-refresh
Focuses: docs Cc:

Description

The "update offer" for auto updates gets retrieved from the updates API, passed between methods, stored in transients, and sent through filters. Its shape should be documented in all these places.

Attachments (3)

51126.diff (1.8 KB) - added by johnbillion 17 months ago.
51126.1.diff (2.1 KB) - added by audrasjb 9 months ago.
Patch refresh
51126.2.diff (11.3 KB) - added by audrasjb 7 months ago.
Added update offer documentation in other functions/hooks

Download all attachments as: .zip

Change History (28)

This ticket was mentioned in Slack in #core-auto-updates by pbiron. View the logs.


17 months ago

@johnbillion
17 months ago

#2 @johnbillion
17 months ago

  • Keywords has-patch added; needs-patch removed

51126.diff is a first pass at this. Needs more work.

#3 @johnbillion
17 months ago

  • Type changed from defect (bug) to enhancement

This ticket was mentioned in Slack in #core-auto-updates by audrasjb. View the logs.


17 months ago

@audrasjb
9 months ago

Patch refresh

#5 @audrasjb
9 months ago

  • Milestone changed from Awaiting Review to 5.8

51126.1.diff refreshes the previous patch and adds descriptions for the $packages URLs.
Moving for 5.8 consideration.

#6 @desrosj
8 months ago

  • Keywords needs-refresh added

I haven't gotten to review this one, but because it's a documentation only change, it can remain in the milestone and be made after the feature freeze date (which is today).

@audrasjb would you be able to refresh the patch to add the description to the other filters and actions receiving the offerings from the API?

#7 @desrosj
8 months ago

This one still needs a refresh. It is beta 1 day today, but this only affects inline documentation, so it can remain for the time being.

This ticket was mentioned in Slack in #core-auto-updates by audrasjb. View the logs.


8 months ago

@audrasjb
7 months ago

Added update offer documentation in other functions/hooks

#9 @audrasjb
7 months ago

  • Keywords needs-refresh removed

Hey @desrosj I refreshed the patch with proper docs for the update offer in other functions/hooks.

#10 @desrosj
7 months ago

  • Owner changed from johnbillion to desrosj
  • Status changed from assigned to reviewing

#11 @desrosj
7 months ago

  • Milestone changed from 5.8 to 5.9

Unfortunately, there are too many other tickets that have been identified that must be fixed for 5.8, so I'm going to punt this one as I won't have the time to thoroughly review. If another committer is able to review and get this one committed prior to RC on Tuesday (29 June), feel free to reassign and shepherd it in.

#13 @audrasjb
2 months ago

I added a PR to make sure the patch is up-to-date against trunk, and also to run the GitHub action tests against these changes so hopefully it could ship in 5.9

#14 @audrasjb
2 months ago

All checks have passed :)

This ticket was mentioned in Slack in #core by audrasjb. View the logs.


2 months ago

This ticket was mentioned in Slack in #core-auto-updates by afragen. View the logs.


2 months ago

#17 @desrosj
2 months ago

  • Keywords needs-refresh added

Finally getting around to dive into this one. I've done some testing, and here are some findings (I'm going to mention these in detail here, and then add comments inline for the PR before adjusting).

For Core auto-updates, it seems there are some parameters still missing. To test, I have a site running 5.7.2. There are two update offerings returned: one for updating to the latest minor in the major version installed, and one for updating to the latest version available. Example responses:

Latest available version.

(
    [response] => autoupdate
    [download] => https://downloads.wordpress.org/release/wordpress-5.8.2.zip
    [locale] => en_US
    [packages] => stdClass Object
        (
            [full] => https://downloads.wordpress.org/release/wordpress-5.8.2.zip
            [no_content] => https://downloads.wordpress.org/release/wordpress-5.8.2-no-content.zip
            [new_bundled] => https://downloads.wordpress.org/release/wordpress-5.8.2-new-bundled.zip
            [partial] => 
            [rollback] => 
        )

    [current] => 5.8.2
    [version] => 5.8.2
    [php_version] => 5.6.20
    [mysql_version] => 5.0
    [new_bundled] => 5.6
    [partial_version] => 
    [new_files] => 1
)

Latest available version within the same major version version:

(
    [response] => autoupdate
    [download] => https://downloads.wordpress.org/release/wordpress-5.7.4.zip
    [locale] => en_US
    [packages] => stdClass Object
        (
            [full] => https://downloads.wordpress.org/release/wordpress-5.7.4.zip
            [no_content] => https://downloads.wordpress.org/release/wordpress-5.7.4-no-content.zip
            [new_bundled] => https://downloads.wordpress.org/release/wordpress-5.7.4-new-bundled.zip
            [partial] => https://downloads.wordpress.org/release/wordpress-5.7.4-partial-2.zip
            [rollback] => https://downloads.wordpress.org/release/wordpress-5.7.4-rollback-2.zip
        )

    [current] => 5.7.4
    [version] => 5.7.4
    [php_version] => 5.6.20
    [mysql_version] => 5.0
    [new_bundled] => 5.6
    [partial_version] => 5.7.2
    [new_files] => 
)

It looks like we're missing:

  • new_files - Indicates when an update package adds files.
  • partial_version - Seems to be the version of WordPress that the partial package URL represents. This package only contains the changed files between two given minor releases and is not available for major updates. It looks like the rollback package also is specific to this version. But there's no code checking this value when attempting a rollback, it just always happens using the rollback package.
  • new_bundled - I believe this is the version number representing when new default themes or plugins are added to instruct the updater to use the new_bundled package URL when CORE_UPGRADE_SKIP_NEW_BUNDLED is undefined or set to false.
  • version - I believe this represents the actual version being offered in the update.
  • response - Update type. From the code, it seems like the following values can be returned: latest, autoupdate, reinstall, upgrade, development.

Some other Core related observations:

  • $current is listed as "The version number of the update offer". But looking at the test info above, it seems to represent the "current" version for the major version range being offered. $version seems to be the actual version being offered in the response.
  • $download seems to be the full update package in both scenarios, but it's not clear whether this is always the case. This could be the "recommended package"?
  • I'm confused by the mysql_version item because it lists 5.0 above in both offerings. WP 5.7 and 5.8 require MyQL 5.6, so this does not quite match up. Clarification on this would be helpful.

For plugins and themes, here are example objects:

Plugins

(
    [id] => w.org/plugins/akismet
    [slug] => akismet
    [plugin] => akismet/akismet.php
    [new_version] => 4.2.1
    [url] => https://wordpress.org/plugins/akismet/
    [package] => https://downloads.wordpress.org/plugin/akismet.4.2.1.zip
    [icons] => Array
        (
            [2x] => https://ps.w.org/akismet/assets/icon-256x256.png?rev=969272
            [1x] => https://ps.w.org/akismet/assets/icon-128x128.png?rev=969272
        )

    [banners] => Array
        (
            [1x] => https://ps.w.org/akismet/assets/banner-772x250.jpg?rev=479904
        )

    [banners_rtl] => Array
        (
        )

    [requires] => 5.0
    [tested] => 5.8.2
    [requires_php] => 
)

Themes

(
    [theme] => twentynineteen
    [new_version] => 2.1
    [url] => https://wordpress.org/themes/twentynineteen/
    [package] => https://downloads.wordpress.org/theme/twentynineteen.2.1.zip
    [requires] => 4.9.6
    [requires_php] => 5.2.4
)

For these, it looks like the following fields are not in the PR yet:

  • id
  • slug
  • new_version
  • url
  • package (as a string and not object)
  • icons
  • banners
  • banners_rtl
  • requires
  • tested
  • requires_php.

The final type of item that could be passed to the filters is for translation updates:

(
    [type] => plugin
    [slug] => akismet
    [language] => en_AU
    [version] => 4.2.1
    [updated] => 2020-03-17 21:00:08
    [package] => https://downloads.wordpress.org/translation/plugin/akismet/4.2.1/en_AU.zip
    [autoupdate] => 1
)

updated and language are different for this type.

Honestly, documenting these different object shapes separately makes more sense than having all these possible entries with "only for plugins", "only for themes and plugins", etc. since they are so different. But that may be the only way to tackle this. I'm not aware of how to document different shapes for the same parameter.

#18 follow-up: @desrosj
2 months ago

I also forgot to add that I'm not sure if there are additional fields that could be returned for each of these types that I haven't encountered in my testing.

@dd32 would you be able to review the .org side of things and confirm the purpose of any field above that was unclear, and share any additional fields that could potentially be returned?

This ticket was mentioned in Slack in #core by audrasjb. View the logs.


2 months ago

#20 follow-up: @marybaum
2 months ago

Per slack conversation:

Before version 5.6, someone had to do manual updates to plugins, themes, and major versions of Core. As of version 5.6 and to this day, all those updates can happen automatically, if you choose. All you do is click an action link on the appropriate page in the WordPress Admin.

#21 in reply to: ↑ 20 ; follow-up: @desrosj
2 months ago

Replying to marybaum:

Per slack conversation:

Before version 5.6, someone had to do manual updates to plugins, themes, and major versions of Core. As of version 5.6 and to this day, all those updates can happen automatically, if you choose. All you do is click an action link on the appropriate page in the WordPress Admin.

@marybaum I think this was meant for a different ticket?

#22 in reply to: ↑ 21 @marybaum
2 months ago

Replying to desrosj:

Oops. I should have asked you which ticket!

Replying to marybaum:

Per slack conversation:

Before version 5.6, someone had to do manual updates to plugins, themes, and major versions of Core. As of version 5.6 and to this day, all those updates can happen automatically, if you choose. All you do is click an action link on the appropriate page in the WordPress Admin.

@marybaum I think this was meant for a different ticket?

#23 in reply to: ↑ 18 @dd32
2 months ago

Replying to desrosj:

I also forgot to add that I'm not sure if there are additional fields that could be returned for each of these types that I haven't encountered in my testing.

I think you're on the money with your descriptions above. If you've got any specific questions about those, feel free to ask me directly.

dd32 would you be able to review the .org side of things and confirm the purpose of any field above that was unclear, and share any additional fields that could potentially be returned?

I'm not sure how I can help here really, the APIs aren't set in stone and there's always the possibility of new fields being added, whether or not core uses them is the important bit. Most of these API's always return all the data they have though, so this is probably all right at the present point.

The main field I see missing above is autoupdate for the plugins/themes endpoint, which can be set to true when a forced-push is available for the plugin/theme. However, there's also #53333 which shows where it could be expanded upon (and where a production API is returning data that WordPress currently isn't using)

This ticket was mentioned in Slack in #core by audrasjb. View the logs.


8 weeks ago

#25 @audrasjb
5 weeks ago

  • Milestone changed from 5.9 to 6.0

Moving this to 6.0 since we're releasing beta 4 right now.

Note: See TracTickets for help on using tickets.