Tech:Upgrading MediaWiki

This page documents the process of upgrading to the next version of MediaWiki on Miraheze.

Normally, this can be followed but there are a few different or extra steps that need to be taken on Miraheze, since we are a wiki farm. This page will contain every step that is to be done, both for guide purposes but also in case users are interested in why it takes time or just how about the process in general.

New MediaWiki releases are generally done twice a year, and we try to upgrade as soon as the stable version is released, however there will be a small period in between when we do tests to make sure that everything works as expected.

These steps do not all need to be done at the same time or even by the same person. Obvious steps such as "read the release notes" or anything that's not an action are not mentioned, but should nonetheless be done.


 * 1) Fetch the new version's corresponding branch (REL1_[X]), fix any conflicts for files, and create a new branch for the @miraheze/MediaWiki repository.
 * 2) Update all extensions to the new version's corresponding branch (REL1_[X]) on the new branch.
 * 3) Check all extensions and skins and see if there are any loading changes (wfLoad or require_once) and create a PR for this to be modified as soon as the upgrade is done.
 * 4) Check if there are any user rights changes. If there are any that should potentially be blacklisted, consult SRE.
 * 5) Check all extensions and skins and and note any SQL changes (such as new files or updated files).
 * 6) * If there are new files that are not patches (i.e. ALTER, DELETE, DROP, etc.) they need to be added either to: $wgCreateWikiSQLFiles (if the extension is globally installed) or to ManageWikiExtensions.php if the extension is not global.
 * 7) *If there are patches, they need to be ran on every wiki using foreachwikiindblist sql.php when the upgrade is performed - make a list of these.
 * 8) Once these steps are done, the branch for test3wiki can be changed to the new version of MediaWiki (via puppet - must be done by an SRE)
 * 9) Run all the SQL patches that have been noted for test3wiki and pull any PRs for other SQL changes locally.
 * 10) Test every extension and skin and make sure that there are no issues with them. If there are issues/errors they should be investigated. If these turn out to be upstream issues, a task should be filed. A reasonable time can be left for upstream to fix the issue or even for a member of the MW team to fix it and submit their patch upstream. If it is apparent that it will not be fixed anytime soon, the extension should be disabled and the upgrade should continue as planned.
 * 11) A date and time should be arranged by the team, and notice for the upgrade should be provided at least one day in advance via a sitenotice, Twitter, Facebook, Discord and IRC.
 * 12) At the agreed time, make all wikis read only. Note that an SRE must be present at this time as the next steps involve depooling.
 * 13) Disable Puppet on all MediaWiki servers and on the Jobrunner servers
 * 14) Switch the default branch to the new MediaWiki version for all MediaWiki and Jobrunner servers (Note: Make sure that puppet is disabled before doing this!)
 * 15) Depool mw8; enable puppet on mw8; run all the patches noted above.
 * 16) Repool mw8; depool mw9; enable puppet on mw9
 * 17) Repool mw9; depool mw10; enable puppet on mw10
 * 18) Repool mw10; depool mw11; enable puppet on mw11
 * 19) Repool mw11
 * 20) Run puppet on both Jobrunners
 * 21) Disbale read-only on all wikis.

The upgrade is now done! Please note that it is important that at least one or two members stay online for an hour or two after the upgrade to make sure that there are no issues, and if anything unexpected does occur to be able to deal with it.