Tech:Upgrading MediaWiki

 An upgrade should not be done on your own, and should be planned in advance with the team

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 note 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 either to: $wgCreateWikiSQLFiles (if the extension is globally installed) or to ManageWikiExtensions.php if the extension is not global.
   • If there are patches, they need to be run on every wiki using mwscript sql.php all when the upgrade is performed – make a list of these.
6. Once these steps are done, the branch for test131 can be changed to the new version of MediaWiki & config (via puppet – must be done by an SRE).
7. Run all the SQL patches that have been noted for betawiki.
8. 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 resolve 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.
9. A date and time should be arranged by the team, and notice of the upgrade should be provided at least one day in advance via a sitenotice, Twitter, Facebook, Discord and IRC.
10. 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.
11. Switch the default branch to the new MediaWiki version for MediaWiki servers. (Note: All deploys outside the upgrade must stop at this point!).
12. Merge the configuration REL1_X branch to master if required (Things may crash here).
13. Push read only commit.
14. Run mwupgradetool on deployment.miraheze.org.
15. Press enter when needed & follow instructions.
16. See RC feeds flow & people smile at the update.

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.