Page MenuHomePhabricator

Deprecate extension.json's manifest_version 1 format in MediaWiki 1.38
Open, LowPublic

Description

We should plan to soft deprecate extension.json's manifest_version: "1" format in MediaWiki 1.38.

Originally I had no plan of ever deprecating version 1, but at this point version 2 is a vastly superior format in terms of validation and helping developers do the right thing. There's also some minor confusion among core developers on which schema they should update (c.f. https://gerrit.wikimedia.org/r/c/mediawiki/core/+/614906/). Once it's soft deprecated, I would consider version 1 frozen, with no new features being added.

Based on extreg-wos, adoption of version 2 looks pretty good (better than I expected tbh). Deprecating in 1.38 means that everyone has had 10 MediaWiki versions to migrate to version 2 (and we're not even breaking it yet...). I expect the number of extensions that will want to support 1.38 and pre-1.28 will be 0.

Depending on how things look, we can look at hard deprecating sometime before 1.43 (LTS if I did my math right).

Before we do this, we need:

Event Timeline

Legoktm created this task.

@Kghbln we had discussed this a few years ago, does this proposal and time table seem reasonable to you?

before 1.43

/me blinks

I'm primarily thinking of the deprecation cycle in terms of LTS. The first LTS the soft deprecation will go out in is 1.39, depending on how uptake is, we'd hard deprecate sometime between then and the next LTS, 1.43. I added extra wording to clarify version 1 will be frozen after soft deprecation, so there should be minimal costs to continuing to support it after that point.

Just for stating the obvious... 1.39 is due ~August 2022. MW 1.43 is therefore ~August 2024

Just for stating the obvious... 1.39 is due ~August 2022. MW 1.43 is therefore ~August 2024

And of course, the support for those is 3 years later..

So 1.39 till mid 2025... 1.43 to mid 2027...

Are there ambiguities in the current v1 manifests that require human input? If not, would it make sense to (indefinitely) keep a standalone class that reads v1 as v2 at run-time?

Are there ambiguities in the current v1 manifests that require human input?

Yes, the main problem is that extension attributes are in the top-level namespace, mixed with core properties. In v1 attributes could be any string while in v2 they're required to be prefixed with the extension name (which gives us the ability to drop attributes for extensions that aren't installed). There's no difference between a typo and an attribute.

If not, would it make sense to (indefinitely) keep a standalone class that reads v1 as v2 at run-time?

Yes-ish. I omitted any removal plan/wording from the task because once we freeze the v1 schema the effort needed to continue supporting it becomes very minimal. All of the code is currently self-contained in ExtensionProcessor, it's probably like 30 lines for v1 support.

Right, so this proposal would also entail that we discontinue adding new properties to both v1 and v2 schemas.

I wonder if it'd be better not to call it "deprecated" but "frozen" instead in that case, so that it's not included in routine conversations about when deprecation/migration is finished and outside of the scope of most "what can we drop" questions.