Making WordPress.org

Opened 4 weeks ago

#8443 new enhancement

Expose update-API version on public `plugin_information` (optional Protect-the-Shire cooldown timing)

Reported by: netanelbaba Owned by:
Priority: normal Milestone:
Component: Plugin Directory Keywords: needs-design-decision api
Cc:

Description

### Problem
Since Protect the Shire / release_delay, a new plugin version can appear on the Plugin Directory and in plugin_information (version, download_link) while update-check / update_source still serves the previous version until the cooldown elapses.

Sites and tooling that treat directory / plugins_api version as ready to install” can show a false update nag during that window. WordPress.org already knows which version is in update_source and when cooldown ends (committer UI: Release_Confirmation::frontend_cooldown_notice(), updater: API_Update_Updater). That signal is not public on the info API.

### Proposal (minimum)
Add one opt-in field on plugin_information (default off for backward compatibility):

  • update_api_version (string) - version currently served via update_source / what update-check offers today. Equals directory version when the release is fully published to the update API.

Clients can compare directory version to update_api_version and suppress false “update available” nags until update-check catches up.

### Nice-to-have
Optional additional opt-in fields, only for Protect-the-Shire / release_delay:

  • release_hold - null, or "cooldown" while release_delay is active for the current release
  • release_hold_until - Unix timestamp (seconds since epoch, UTC); set only when release_hold is "cooldown", otherwise null

Compute cooldown timing with the same helpers as the committer cooldown UI / API_Update_Updater. Clients should not hardcode delay hours.

### Inferability
The directory vs update-check version gap is already public. Timed cooldown fields make that gap easier to interpret: while release_hold is "cooldown", the lag is Protect the Shire; after cooldown ends (or with no hold) and update_api_version still lags, observers can more confidently read a non-cooldown hold. That reading is already possible from a lasting mismatch today; cooldown timing mainly shortens the ambiguity window. Shipping update_api_version alone leaves inference where it is today. Meta’s call on how much timing to publish.

When a release is not in Protect-the-Shire cooldown, leave release_hold / release_hold_until unset; still return an accurate update_api_version.

### Update-check (Meta follow-up)
The update-check service is closed-source. Please consider mirroring at least update_api_version there for clients that never call plugins_api. Optional: mirror cooldown hold fields if those ship on info.

### Non-goals

  • Changing cooldown duration or bypass policy (plugins@wordpress.org)
  • A public security-block label, scanner findings, or risk scores
  • Overloading empty package as a hold signal
  • Overlap with phased rollout / disable_autoupdate (standalone/plugin-update-helpers.php)

### References

Change History (0)

Note: See TracTickets for help on using tickets.