You are browsing a read-only backup copy of Wikitech. The primary site can be found at wikitech.wikimedia.org

PHP upgrade process for MediaWiki

From Wikitech-static
Jump to navigation Jump to search

PHP Upgrade Process for MediaWiki at WMF.

Preparation for MediaWiki

This applies to every new PHP version that MediaWiki supports, including intermediary versions of PHP that WMF does not install. For example, while WMF stayed on PHP 7.4, MediaWiki added support for PHP 8.0, 8.1, 8.2, and 8.3. WMF then upgraded to PHP 8.1.

This is partly for efficiency, because it means WMF will only have to maintain Debian packages for PHP versions that it deploys, and thus these steps start with sury.org with only the production versions eventually switching to wikimedia.org.

  1. CI: Create docker images in integration/config.git with PHP X.Y using Debian packages from sury.org. These are for the Jenkins "Quibble" jobs.
  2. CI: Create Jenkins jobs with PHP X.Y, and enable as "experimental" in Zuul for all MediaWiki repositories. Experimental jobs only run when someone comments "check experimental" in Gerrit and do not block code review, because they likely do not pass yet at this point.
  3. DX: Create docker images in releng/dev-images.git with PHP X.Y. These let MediaWiki-Docker users opt-in and reproduce/discover/fix issues locally.
  4. MW: Make CI for MediaWiki core and WMF extensions pass on PHP X.Y.
    • Initial review of upstream PHP X.Y announcements, deprecations, changelog, and RFCs. Create tasks for relevant changes that might affect MediaWiki core/extensions in a prominent or difficult-to-migrate way, so that we can plan ahead. Especially if it affects a stable or public MediaWiki API, or a third-party Composer package that MediaWiki depends on where an upstream must make changes first. Report such issues to relevant upstreams, and try to send a pull request along with it.
    • Initial review of MediaWiki Composer dependencies (identify any semver-major upstream releases that we cannot apply today due to a too-high PHP version requirement, that our upcoming PHP X.Y upgrade would unblock). Create subtasks for each of these, so that people can work on preparing code to be forward-compatible with the next major version of these dependencies (we will apply these composer upgrades during the post-rollout phase, before the MW release branch cut).
    • Fix deprecation warnings in MediaWiki core and WMF-deployed extensions (enough for CI to pass).
    • Create subtasks for any non-trivial failures detected by PHPUnit.
    • Promote Jenkins jobs with PHP X.Y on MediaWiki core and WMF-deployed extensions from "experimental" to "gate-and-submit" pipeline. This CI enforces that they must pass and block code review.
  5. DX: Switch MediaWiki-Docker default to PHP X.Y, thus matching the next PHP version that WMF will deploy. This is configured in mediawiki/core.git:/docker-compose.yml.

Preparation for WMF

Adoption of Debian packages from wikimedia.org in CI and DX serves several purposes:
  • It avoid regressing or delaying migration of CI and local workflows that rely on packages that otherwise might not be available.[1]
  • It increases the value (ROI) of everyone's CI and local development activities at no extra cost.
  • It increases confidence in the results by avoiding situations where the "PHP X.Y" local/CI env is taken to be the same as prod, but then revealed to have a difference not found until production due to differences in package versions or otherwise missing backports for bugs already known and fixed.
  1. SRE: Create Debian packages for PHP X.Y and upload to apt.wikimedia.org.
  2. CI: Switch PHP X.Y images in integration/config.git from sury.org to wikimedia.org and apply to Jenkins jobs.
  3. DX: Switch PHP X.Y images in releng/dev-images.git from sury.org to wikimedia.org and apply update to MediaWiki-Docker. This is configured in mediawiki/core.git:/docker-compose.yml.
  4. SRE: Create production images for PHP X.Y and add new flavour to MediaWiki deployments. This means Scap deployments will build both container flavours going forward. The new PHP X.Y flavour is for internal use, only to facilitate creation of the title-case mapping. Once that is done, the image can be exposed publicly via mw-debug/next.
  5. SRE: Generate and deploy title-case mapping in MediaWiki configuration (wmf-config/UcfirstOverrides.php). This ensures page titles and user names remain unchanged during the upcoming upgrade, by overriding the "next" PHP version to behave the same as the "old" PHP version.
  6. SRE: Switch mw-debug/next to PHP X.Y images, for public opt-in testing via WikimediaDebug. By this point, the infrastructure for mw-on-k8s is ready to begin the rollout.
  7. Beta Cluster: Switch to PHP X.Y, includes writing Puppet changes to support PHP X.Y on baremetal. By this point, the infrastructure for baremetal servers (parsoidtest and deployment server) is ready for rollout.

Test

  1. MW: Start monitoring and fixing deprecation warnings as found in Logstash. Create a tracking task (e.g. T401855) and regularly monitor Logstash for production errors that are PHP deprecations, create tasks for them, tag with PHP X.Y (e.g. #php_8.3_support), and attach them as child tasks under this tracking task. Review existing tasks on the PHP X.Y Phabricator board and make progress on those (either directly or by escalating to someone in/outside the team).
  2. QTE, MW, SRE: One week for validation and end-to-end testing via WikimediaDebug "next" and Beta Cluster. This is the last oppertunity to discover and resolve blockers early, before rolling out to a small percentage of real traffic.
  3. SRE, MW: Benchmarking for PHP X.Y, check specific well-known workloads to idetnify regressions or suboptimal configurations (e.g. benchmw with URLs, and CLI benchmarkParse.php). Previous examplesː T383805, T280497.

Rollout

  1. SRE: Ramp up mw-api-ext and mw-web cluster (cookie-based).
  2. SRE: Ramp up mw-api-int and mw-jobrunner.
  3. SRE: Ramp up mw-api-ext and mw-web cluster (remaining).
  4. SRE: Switch other mw-on-k8s server groups (mw-script, mw-cron, mw-experimental, mediawiki-dumps-legacy, etc) and the deployment server.

Post-rollout

To take place before the next MW release branch cut, but after the rollout. The branch is generally cut two months before the release month (e.g. in April if the release is in June). mw:Version lifecycle

  1. MW: Raise minimum PHP version if applicable, as expected under policy (table).
  2. MW: Upgrade vendor dependencies if applicable.

To take place after the rollout, and after the MW release branch cut (e.g. late April or early May, if the release is in June)

  1. SRE: Turn down cookie-based routing and other "next" handling, validating that no workloads still run on the old PHP version (which would hard-fail at this point).
  2. SRE: Remove emulating of old-php title-case mapping. T394556

Post-rollout (MediaWiki release)

See mw:Release checklist.

Out of scope

The following may be associated or historically paired with PHP upgrades that are now handled separately:

  • OS upgrade (Debian Linux).
  • libicu upgrades (Re-indexing and re-encoding the MediaWiki category collations).
  1. ↑ For example: In July 2025, Wikimedia created a Debian package for php-xhprof and started hosting it on apt.wikimedia.org. At the time of writing, upstream Debian does not provide xhprof in any of the "stable" or "testing" channels.
Retrieved from "https://wikitech-static.wikimedia.org/w/index.php?title=PHP_upgrade_process_for_MediaWiki&oldid=636535"