Make WordPress Core

Opened 4 years ago

Last modified 18 months ago

#51126 reviewing task (blessed)

Document the update offer parameter for auto updates

Reported by: johnbillion's profile johnbillion Owned by: desrosj's profile desrosj
Milestone: Future Release Priority: normal
Severity: normal Version:
Component: Upgrade/Install Keywords: has-patch changes-requested
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 4 years ago.
51126.1.diff (2.1 KB) - added by audrasjb 3 years ago.
Patch refresh
51126.2.diff (11.3 KB) - added by audrasjb 3 years ago.
Added update offer documentation in other functions/hooks

Download all attachments as: .zip

Change History (42)

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


4 years ago

@johnbillion
4 years ago

#2 @johnbillion
4 years ago

  • Keywords has-patch added; needs-patch removed

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

#3 @johnbillion
4 years ago

  • Type changed from defect (bug) to enhancement

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


4 years ago

@audrasjb
3 years ago

Patch refresh

#5 @audrasjb
3 years 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
3 years 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
3 years 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.


3 years ago

@audrasjb
3 years ago

Added update offer documentation in other functions/hooks

#9 @audrasjb
3 years ago

  • Keywords needs-refresh removed

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

#10 @desrosj
3 years ago

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

#11 @desrosj
3 years 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 years 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 years ago

All checks have passed :)

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


2 years ago

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


2 years ago

#17 @desrosj
2 years 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 years 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 years ago

#20 follow-up: @marybaum
2 years 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 years 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 years 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 years 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.


2 years ago

#25 @audrasjb
2 years ago

  • Milestone changed from 5.9 to 6.0

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

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


2 years ago

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


2 years ago

#28 @costdev
2 years ago

  • Type changed from enhancement to task (blessed)

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


2 years ago

#30 @afragen
2 years ago

Consider adding a doc comment that "additional properties may also be present"

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


23 months ago

#32 @chaion07
23 months ago

  • Keywords changes-requested added; needs-refresh removed

Thanks @johnbillion for reporting this. We reviewed this ticket during a recent bug-scrub session for WP 6.0 and based on the feedback we're making the following changes:

  1. Removing the needs-refresh keyword
  2. Adding the changes-requested keyword

Props to @costdev

Cheers!

#33 @costdev
23 months ago

  • Milestone changed from 6.0 to 6.1

With 6.0 RC1 starting soon, I'm moving this to the 6.1 milestone.

This ticket was mentioned in Slack in #docs by pbiron. View the logs.


22 months ago

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


20 months ago

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


20 months ago

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


19 months ago

#38 @costdev
19 months ago

  • Keywords dev-feedback added

Per the discussion in the bug scrub, I'm pinging @dd32 and @desrosj for their perspectives on what needs to be done, where, and by who to move this ticket forward. 🙂

#39 @desrosj
18 months ago

  • Keywords dev-feedback removed
  • Milestone changed from 6.1 to Future Release

I'm punting this to Future Release for now.

This needs a new patch from myself (unless someone else wants to take a pass at it), but I don't think I'll have enough time to create one (or review one from someone else) in the next week or two with higher priorities still to tackle.

This is on my list though.

Note: See TracTickets for help on using tickets.