Page MenuHomePhabricator

RFC: Stop supporting legacy PHP entry point extensions
Open, MediumPublic

Description

Motivation

extension.json was introduced in 1.25 (just about 10 releases/5 years ago). It has many superior features including being able to properly declare dependencies, ability to set extension "attributes" (which have better performance possibilities) and schema validation.

However, continuing to support legacy PHP entry points means we can't fully take advantage of those features. Every extension integration point with core must still come along with a $wg variable and we can't do a wholesale migration of existing globals to attributes either.

Then there's stuff like T258844: Make the web installer work without running any extension PHP code which would be nice to have but has never even been in the realm of possibilities as long as PHP entry point extensions exist.

Requirements

I would disclaim that it's not actually possible to stop people from running/loading PHP code from LocalSettings.php, but that's not the point.

  • Deprecate using legacy PHP entry points for extensions (ideally before 1.39 LTS)
    • Start coordinated push to convert remaining extensions in Gerrit to extension.json
    • Invite maintainers to ask for help / request missing features so I and other core devs can help them with migration
    • Assess migration status to figure out when removal can be done.
  • Stop supporting legacy PHP entry points for extensions (ideally before 1.43 LTS)
    • Drop support from web installer
    • Begin deprecation of globals (e.g. $wgExtensionCredits) that were only intended for extensions and migrate them to attributes (following the normal deprecation process)
    • Eventually drop support from CI (once no supporting release branches remain)

Exploration

Nearly 85% of extensions in Gerrit use extension.json.

Event Timeline

Legoktm created this task.Jul 24 2020, 10:39 PM
Restricted Application added a subscriber: Aklapper. · View Herald TranscriptJul 24 2020, 10:39 PM

I just want to mention that the last WMF-deployed extension that needed legacy php entry point was Wikibase (Repo and Client) which as of yesterday, they all work with extension.json now, Client is already deployed in production and repo will be deployed in a couple of weeks (once we are sure it doesn't have any bugs).

TK-999 added a subscriber: TK-999.Jul 28 2020, 12:20 PM
Krinkle moved this task from P1: Define to P3: Explore on the TechCom-RFC board.Jul 29 2020, 8:27 PM
Krinkle added a subscriber: Krinkle.

If I understand correctly the main "problem" we want to solve is:

  • Cost of maintennace for core developers.
  • Cost of support for this in the rest of the stack and ecosystem (e.g. installer).
  • Confusion for new users of MediaWiki that they might need to learn about, understand, operate and debug two ways of installing an extension.

Moving forward as such with a clear problem statement and code owner and resourcing clarified.

Why wait so long? We're about to release 1.35 as an LTS release that has support for PHP entry points. It seems fine to me for 1.39 (the next LTS release ~2 years from now) to not support PHP entry points. I don't know what that means in terms of the deprecation timeline: maybe we soft-deprecate it in 1.35, hard-deprecate in 1.36 and remove in 1.37? Either way, I want to challenge the notion that 1.39 needs to still support this.

Legoktm added a comment.EditedJul 29 2020, 9:13 PM

If I understand correctly the main "problem" we want to solve is:
<snip>

Yep, that's a good summary.

Why wait so long? We're about to release 1.35 as an LTS release that has support for PHP entry points. It seems fine to me for 1.39 (the next LTS release ~2 years from now) to not support PHP entry points. I don't know what that means in terms of the deprecation timeline: maybe we soft-deprecate it in 1.35, hard-deprecate in 1.36 and remove in 1.37? Either way, I want to challenge the notion that 1.39 needs to still support this.

More philosophically, I've tried very hard to not make any breaking changes to the extension loading system (not counting changes in MediaWiki that require extensions to change), ever since extension.json was introduced, we've never made a breaking change to the formatwe've only made one breaking change (the introduction of manifest_version). This (along with T258668) are going to be the first real breaking changes to the format and structure of how extensions are loaded since they were introduced basically. As such, I want to move slowly and give people necessary advance notice. Also during the extension.json rollout, I told people (usually informally) that PHP entry points were expected to keep working. Now that we're changing that, I don't want to just pull the rug out from under them with minimal notice. I don't think our normal deprecation timelines are suitable for this kind of a change.

Practically, if an extension has not moved to extension.json yet, there's a decent chance it needs a lot of work to do so! Or it needs some feature added to extension.json that isn't trivial and needs some planning/work to implement. Then there's updating all the different documentation, templates, etc. I'm not confident that could all be done at a level of quality that I'd be satisfied with by 1.39. So I'd rather take it slower.

Practically, if an extension has not moved to extension.json yet, there's a decent chance it needs a lot of work to do so! Or it needs some feature added to extension.json that isn't trivial […]

The only one I'm aware of, both past and present, is Wikibase using the entrypoint for different configuration presets. But for anything else that was at some point not natively supported in extension.json would it not generally have been trivial to place the same PHP code in a registration callback? What is the bare minimum we need in an extension.json to be useful to developers and to be useful to core and installer developers in terms of the above benefits?

As the person who was involved in migrating Wikibase from php entry point to extension.json I want to say I support this RFC. Even though Wikibase have a pretty entangled and complicated relationship with core and migration was quite a hassle and definitely a php entry point would be easier but having a free-form, whatever-you-like, and highly dependent on global variables entry point is not a clean practice and prone to break quite easily which happened several times already (even at the end the json file ends up modifying the global variables as well but at least it's hidden behind a layer of abstraction and changeable in the future)

Practically, if an extension has not moved to extension.json yet, there's a decent chance it needs a lot of work to do so! Or it needs some feature added to extension.json that isn't trivial […]

The only one I'm aware of, both past and present, is Wikibase using the entrypoint for different configuration presets. But for anything else that was at some point not natively supported in extension.json would it not generally have been trivial to place the same PHP code in a registration callback?

If we just move whatever PHP code into a callback, that doesn't give us the ability to remove the PHP globals since extensions may still be depending upon them. Also callbacks are executed later than PHP entry points, which generally causes problems if sysadmins are expected to manipulate already-existing config in LocalSettings.php. If we have to change how the extension's config works, that may require its own deprecation/migration period too.

What is the bare minimum we need in an extension.json to be useful to developers and to be useful to core and installer developers in terms of the above benefits?

I think if we're going to require people to migrate I'd rather we just do it correctly all at once, even if that takes more time now.