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.

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.
 * 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) Switch the default branch to the new MediaWiki version for MediaWiki servers. (Note: All deploys outside of the upgrade must stop at this point!)
 * 14) Merge the configuration REL1_X branch to master if required (Things may crash here)
 * 15) push read only commit
 * 16) Depool mw11 (reduces load, more risk on this server)
 * 17) Copy the mediawiki upgrade script from RhinosF1 to your homedir [link coming] on deployment.miraheze.org
 * 18) run the script with python3 on deployment.miraheze.org
 * 19) press enter when needed & follow instrucions
 * 20) see RC feeds flow & everyone smile at the update
 * 21) Repool mw11