No, backwards compatibility should not be broken yet. In general,
there should be a major release between deprecating code and removing
it. While
https://www.mediawiki.org/wiki/Stable_interface_policy#Removal
doesn't explicitly apply to the command line interface, it's still a
good guide.
AntiCompositeNumber
(he/him)
On Mon, Jan 9, 2023 at 6:31 PM <novemlinguae(a)gmail.com> wrote:
>
> Hey Daniel,
>
>
>
> Thanks for the email. Is any refactoring of the maintenance scripts themselves
suggested yet? e.g. removing the top and bottom boilerplate?
>
>
>
> Thanks,
>
> Novem Linguae
>
>
>
> From: Daniel Kinzler <dkinzler(a)wikimedia.org>
> Sent: Monday, January 9, 2023 12:30 PM
> To: Wikimedia developers <wikitech-l(a)lists.wikimedia.org>
> Subject: [Wikitech-l] Deprecation: directly invoking maintenance scripts
>
>
>
> 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 standalone PHP 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
>
> _______________________________________________
> Wikitech-l mailing list -- wikitech-l(a)lists.wikimedia.org
> To unsubscribe send an email to wikitech-l-leave(a)lists.wikimedia.org
>
https://lists.wikimedia.org/postorius/lists/wikitech-l.lists.wikimedia.org/