Deprecation: directly invoking maintenance scripts - Wikitech-l

9 Jan 2023

TLDR: Invoking maintenance scripts directly will be deprecated in MW 1.40, use 
maintenance/run.php instead. This affects anyone managing a MediaWiki 
installation, for development, testing, or production use.

Until now, MediaWiki maintenance scripts have been handled standalonePHP scripts 
- for instance, to run the script that outputs the MediaWiki version, you would use:
...
  php maintenance/version.php

Starting with MediaWiki 1.40, this is deprecated. The preferred way to run 
maintenance scripts is now by name, using the maintenance runner:
...
  php maintenance/run.php version

Similarly, the preferred way to run the updater is now:
...
  php maintenance/run.php update

The script to run cal also be specified using the full path of the script file, 
or the full PHP class name of a subclass of the Maintenance class. For more 
details, run
...
  php maintenance/run.php --help

Rationale and History:

Treating maintenance scripts as standalone PHP scripts requires some boilerplate 
code to be present at the top and at the bottom of every file. This is error 
prone and makes it difficult to update the maintenance framework. But more 
importantly,
for this boilerplate to work, the location of the MediaWiki installation has to 
be known relative to the maintenance script, which is not reliably possible for 
scripts defined in extensions.

A similar problem arises if the maintenance script needs a base class other than 
the default Maintenance class: since the class is loaded before MediaWiki is 
initialized, the autoloader is not yet in place, and the file containing the 
base class needs to be included explicitly.

These and similar issues can be avoided by creating a wrapper script that loads 
and executes the actual maintenance class. This way, the maintenance wrapper can 
initialize MediaWiki before passing control to the script.

I propose creating such a wrapper as an RFC in 2018 (T99268)[^1], which was 
approved in 2019.  However, implementing the proposal proved challenging, and 
soon stalled. I picked it up again as a side project after working on 
overhauling the configuration and bootstrapping code in early 2022: With the 
introduction of SettingsBuilder, it became much simpler to create a 
MaintenanceRunner class, because it was no longer necessary to juggle global 
variables.

Several bits and pieces got reviewed and merged over the course of 2022 (shout 
out to Amir, Tim, Timo, and everyone who contributed). Now the runner is ready, 
and we should stop calling maintenance scripts directly.

For now, existing maintenance scripts will function both ways[^2] : when called 
using the runner, or directly. However, newly created maintenance scripts should 
not be required to be callable as standalone scripts. So it's best to change all 
callers to use the wrapper.

This should now work for nearly all[^2] cases, though there are still a couple 
of rough edges to be smoothed out. If you are running MediaWiki 1.40, please try 
the new mechanism, and report any isses on Phabricator.

Thanks,
Daniel

[^1] https://phabricator.wikimedia.org/T99268
[^2] with the exception over very old-school scripts that do not use the 
Maintenance base class and rely on CommandLineInc.php instead.

-- 
Daniel Kinzler
Principal Software Engineer, Platform Engineering
Wikimedia Foundation