[wp-trac] [WordPress Trac] #51126: Document the update offer parameter for auto updates

[WordPress Trac]

#51126: Document the update offer parameter for auto updates
-------------------------------------+------------------------
 Reporter:  johnbillion              |       Owner:  desrosj
     Type:  enhancement              |      Status:  reviewing
 Priority:  normal                   |   Milestone:  5.9
Component:  Upgrade/Install          |     Version:
 Severity:  normal                   |  Resolution:
 Keywords:  has-patch needs-refresh  |     Focuses:  docs
-------------------------------------+------------------------
Changes (by desrosj):

 * keywords:  has-patch => has-patch needs-refresh


Comment:

 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.

-- 
Ticket URL: <https://core.trac.wordpress.org/ticket/51126#comment:17>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform