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) Create a REL1_[X] branch on the config repo to apply breaking changes to.
 * 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 mwscript sql.php all 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 & config (via puppet - must be done by an SRE)
 * 9) Run all the SQL patches that have been noted for test3wiki.
 * 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. Ensure logs are checked for warnings, these may not be user visible but can easily overwhelm logging.
 * 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 mw11 (current canary server).
 * 14) Switch the default branch to the new MediaWiki version for MediaWiki servers. (Note: All deploys outside of the upgrade must stop at this point!)
 * 15) Merge the configuration REL1_X branch to master if required (Note: Puppet will auto deploy config changes so must be stopped!)
 * 16) run check-read-only on all appservers
 * 17) Depool mw11 (reduces load, more risk on this server); enable puppet if disabled; run deploy-mediawiki with --servers=skip; run all patches; check read only remains.
 * 18) run deploy-mediawiki for mw8
 * 19) run deploy-mediawiki for mw9
 * 20) run deploy-mediawiki mw10
 * 21) etc for any new servers not listed yet
 * 22) Run deploy-mediawiki for --servers=all (task/jobchron)
 * 23) Repool mw11
 * 24) Disable read-only on all wikis.
 * 25) run check-read-only everywhere and see RC feeds flow

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.