Tech:Upgrading MediaWiki

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 it is done.

New MediaWiki releases are generally done twice a year, and we try to upgrade as soon as the stable version is released.

Note: 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.


 * Please review the Upgrade Blockers column on the MediaWiki Phabricator board before starting an upgrade.

MW - Steps that need to be done by a MW Admin

SRE - Steps that can only be done/merged by Site Reliabilty Engineering


 * 1) MW  Fetch the new versions corresponding branch (REL[VERSION]), fix conflicts for files, and create a new branch for the Miraheze/MediaWiki repository.
 * 2) MW  Check all extensions and skins and see if there are any loading changes (wfLoad or require_once).
 * 3) MW  Check if there are any user rights changes. If in doubt whether we need to blacklist them speak to SRE.
 * 4) MW  Check all extensions and skins and see if there are any SQL changes (such as new files or updated files). If there are new files that are not patches (i.e. ALTER, DELETE, DROP, etc.) they need to be added to $wgCreateWikiSQLFiles (only if the extension is globally installed and not in ManageWikiExtensions.php). You also need to add any new files to ManageWikiExtensions.php. If there are patches, they just need to be ran on every wiki using sql.php when the upgrade is performed - make a list of these.
 * 5) SRE  Change branch on test1wiki to the new version of MediaWiki.
 * 6) MW  Run update.php for test1wiki.
 * 7) MW  Make sure that all extensions and skins are compatible with the new version of MediaWiki. If there are any errors then they should be investigated, and if it is an obvious upstream issue, it should be filed and the extension in question should be disabled for the time being.
 * 8) MW  After it is made sure that the new version works fine on test1wiki, the actual upgrade can start. Set a time for the upgrade, and if it is in the next few hours make a sitenotice (and Twitter and Facebook notices are also a good idea)
 * 9) MW  Make all wikis read-only and have a sitenotice saying that they are being upgraded
 * 10) Note: These following steps are marked as "Site Reliability Engineering" as they need to be ran at the same time as SRE-required steps
 * 11) SRE  Disable Puppet on mw* and depool mw1
 * 12) SRE  Switch default branch to new branch for mw*
 * 13) MW  Run update.php on all wikis
 * 14) SRE  Run all ALTER statements mentioned above.
 * 15) SRE  Switch depool to mw2 and run puppet
 * 16) <abbr class="newpage" title="Site Reliability Engineering">SRE  Repool mw2
 * 17) <abbr class="newpage" title="Site Reliability Engineering">SRE  Switch depool to mw3 and run puppet
 * 18) <abbr class="newpage" title="Site Reliability Engineering">SRE  Repool mw3

The upgrade is done!