Page MenuHomePhabricator

Document extensions' MediaWiki version compatibility better
Open, MediumPublic

Description

Problem

Extensions are (supposed to be) documented on a page on MediaWiki. This documentation includes Template:Extension to provide a summary of important information about the extension, including the "required version of MediaWiki".

This version field is inadequate: does specifying "1.19+" mean that the extension's master branch is intended to be compatible with MediaWiki 1.19, or that the extension has release branches going back to REL1_19 while the extension's master branch is only intended to be compatible with MediaWiki core's master branch, or perhaps some middle ground?

Some extensions have solved this by including detailed text in the existing "version" parameter, such as "1.26+ . Flow master is only supported with core's master; otherwise, use matching branches (e.g. Flow REL1_26 with core REL1_26, or matching WMF release branches).", but this is currently done inconsistently and infrequently.

Who would benefit

Developers making updates to extensions for a core change in compliance with the new deprecation policy will no longer have to guess at whether backwards compatibility with older versions of MediaWiki core should be maintained.

Developers of extensions that don't maintain compatibility with old versions of MediaWiki won't have unnecessary and sometimes complex backwards-compatibility code added.

Developers of extensions that do maintain compatibility with old versions of MediaWiki won't have to -1 or -2 as many changes that break backwards compatibility.

Proposed solution

  1. Update Template:Extension with parameters to indicate the MediaWiki versions for which release branches exist versus the MediaWiki versions the extension's master branch maintains compatibility with.
  2. Update existing extension pages to use these parameters, which may involve determining the master-compatibility policy where it's not already specified.

Event Timeline

Anomie created this task.Jan 27 2017, 5:29 PM
Restricted Application added a subscriber: Aklapper. · View Herald TranscriptJan 27 2017, 5:29 PM

Generally +1. As usual I'm wondering though how to make maintainers such info updated (a general issue with our hundreds of extension homepages on mw.org often missing basics such as license info) and if any assumptions should be made or not.

That would easily end up as "complex to update" though if there was something like

  • ☑ - REL1_23 branch for MW 1.23
  • ☑ - REL1_27 branch for MW 1.27
  • ☑ - REL1_28 and Master branch for MW 1.28
  • ? - Master branch for MW 1.29
Tgr awarded a token.Jan 27 2017, 7:05 PM

That example would probably be stated as "REL branches from 1.23, master supports 1.28+". Eventually the extension's developers would decide to increase that 1.28. The other common pattern is "REL branches from 1.X, master only supports master". Then there are extensions that are no longer maintained, such as OpenSearchXML, so they don't have a useful master branch anymore.

The nice thing about how our REL branches work is that when 1.29 is released every extension in Gerrit gets a REL1_29 created automatically. If there's any extension that is missing some REL branch in the sequence since the move to Gerrit, I'd think Release Engineering would want to know about the bug. For this proposal I'm not at all concerned about extensions not in Gerrit.

Tgr added a subscriber: Tgr.EditedJan 27 2017, 7:15 PM

IMO

  • add a compatibility policy parameter; with compatibility policy=master, a mediawiki=1.19+ parameter would mean that the extension master is compatible with MW 1.19+; with compatibility policy=rel, a mediawiki=1.19+ parameter means that the extension master only needs to be compatible with MW master, and the extension has working RELx_xx branches going back to 1_19.
  • maybe add an oldest mediawiki parameter which is the first MW version that's supported by some (old) version of the extension. This only makes sense for compatibility policy=master (otherwise it would always have the same value as the mediawiki parameter) and will never change for a given extension. Might not be worth the effort, since it's not interesting information for developers and only interesting for users if they are willing to dig up which commit to the extension updated MW requirements (although for extensions using extension.json that could in theory be mined automatically).

Agree. We should distinguish three (or just two?) extension branching models:

  • REL1_XX with compatibility for each MediaWiki version, master does not keep compatibility with previous versions.
  • master keep compatibility with previous versions, so REL1_XX probably not needed. Still I think there's some version where support on master should end, but this is hard to tell and changes over time.
  • REL1_XX branches not supported (even if they exist) and master only works with latest version or LTS (see T149508#2754752). This is probably the same as the first point except that the maintainer doesn't bother to fix it for specific branches, but any other contributor can probably contribute to fix them.

Since model 1 is the expected behavior IMHO, it may be good idea also to note when it's not in the README of such extensions.

Still I think there's some version where support on master should end, but this is hard to tell and changes over time.

There are extensions where the version at which support on master ends is documented. Think of it like how MediaWiki core currently supports PHP 5.5.9 and later, even though 1.26 supported back to 5.3.

(Also wondering how this could be related to T155029: MediaWiki.org: Generate infoboxes from extension.json in git; just linking)

Tgr added a comment.Jan 27 2017, 10:22 PM

(Also wondering how this could be related to T155029: MediaWiki.org: Generate infoboxes from extension.json in git; just linking)

In the current form, it's not. We could store the information in extension.json though and eventually reuse that in the template. I guess ExtensionDistributor could use that to give you the master tarball for older versions.

Nikerabbit added a subscriber: Nikerabbit.
cicalese added a subscriber: cicalese.

The nice thing about how our REL branches work is that when 1.29 is released every extension in Gerrit gets a REL1_29 created automatically.

While that is, in general, a good thing, it is a problem when there is a change in MediaWiki core that breaks an extension. The existence of the new release branch gives the impression that the extension works with that MediaWiki version, where it really just means that the extension existed in Gerrit on the day of the MediaWiki release. Then, unless the extension developer makes a habit of backporting fixes to the release branch, the release branch will never be correct for that release, and ExtensionDistributor will provide a broken extension. I'm not sure what a good solution to this is, but I just wanted to point out the danger in assuming that the existence of a release branch indicates that the extension works with that release.

For an extension that's actively maintained with MediaWiki core's master, the automatic creation of release branches is helpful because it means that a snapshot of the working version is taken when a new core release is made. But you're right, for an extension that's not being actively maintained it means the release snapshot will be broken too.

For extensions that are unmaintained, that is definitely true. Not to split hairs, but for extensions that I would consider actively maintained, I guess it depends upon what version of MediaWiki is being used for their development: master or the current release. We typically develop our extensions with the current release of MediaWiki. That way we can continue to deliver new features in updated versions of our extensions on a stable MediaWiki version. We typically wait until the next MediaWiki release has been officially released to test with it and fix any issues that arise. We do try to remember to backport those fixes to the current release branch, but there is a period before that happens in which, if extension is not compatible with the new MediaWiki version, the release branch is broken.

RHeigl added a subscriber: RHeigl.

Meets a requirement of the MediaWiki Usage Report 2015: extension management

Tgr added a comment.Jan 31 2017, 10:42 PM

The existence of the new release branch gives the impression that the extension works with that MediaWiki version, where it really just means that the extension existed in Gerrit on the day of the MediaWiki release.

That's partially solved by this proposal - as long as we have a machine-readable record of which maintainers support release branches and which don't, we can make ExtensionDistributor behave more intelligently (which we couldn't do right now).

It might make sense to have some system where extension maintainers can sign off on releases but that's an orthogonal issue.

This project is selected for the Developer-Wishlist voting round and will be added to a MediaWiki page very soon. To the subscribers, or proposer of this task: please help modify the task description: add a brief summary (10-12 lines) of the problem that this proposal raises, topics discussed in the comments, and a proposed solution (if there is any yet). Remember to add a header with a title "Description," to your content. Please do so before February 5th, 12:00 pm UTC.

Tgr added a comment.EditedMay 12 2017, 1:13 PM

Added the compatibility policy parameter (doc1, doc2, template, templatedoc, backlog, announcement). Time to update your extensions!

Kghbln added a subscriber: Kghbln.
greg added a subscriber: greg.May 21 2017, 12:40 PM
Tgr moved this task from Backlog to Pending on the User-Tgr board.Jun 12 2017, 12:11 PM
Krinkle removed a subscriber: Krinkle.
Tgr added a comment.Jan 20 2018, 2:49 AM

Updated other pages that I could find talking about extension compatibility to reference Compatibility#MediaWiki_extensions:

Tgr added a comment.Jan 20 2018, 3:02 AM

What's left to do here before marking as resolved?

  • The second bullet point from T156500#2977431 is not done but as I said I'm not convinced it's worth the effort. If no one feels strongly about it, I'd say drop it. (I might be biased though as I strongly prefer the release branch policy.)
  • Most extensions don't declare a policy. Some kind of campaign to fix that? Now that this is sort of part of an annual goal, maybe DevRel is interested in driving it.

There has been a MediaWiki (=supported MW core versions) field in that template (currently non-empty for 1581 extensions; empty for 310 extensions).
Now there is also a Compatibility field (currently non-empty for 109 extensions).
Either I'm not sure there's a use case for both to exist in parallel, or I simply don't get it?

If "Compatibility" is "master", then "MediaWiki" says what version of MediaWiki is supported by the extension's master branch.

If "Compatibility" is "release branches", then I suppose "MediaWiki" is less important. Probably it indicates the earliest version of MediaWiki for which the extension has a release branch, although I suppose it could be used to indicate which release branches will get bugfixes (if that's more or less than the currently supported versions of MW core).

Does T156500#4504104 refer to the "Compatibility" parameter or the "Compatibility policy" parameter? https://www.mediawiki.org/wiki/Template:Extension#Content_parameters. T156500#3258508 and T156500#4507720 refer to the latter (compatibility policy, NOT compatibility).

(Also wondering how this could be related to T155029: MediaWiki.org: Generate infoboxes from extension.json in git; just linking)

In the current form, it's not. We could store the information in extension.json though and eventually reuse that in the template. I guess ExtensionDistributor could use that to give you the master tarball for older versions.

I like this idea. However I would prefer the additional possibility to provide key-value-pairs (extension commit id or tag to MediaWiki version.)

For example, I would like to specify something like that:

MW 1.19-1.22 -> Extension 2.1
MW 1.23-1.28 -> Extension 2.2
MW 1.29-1.31 -> Extension 2.4
MW master    -> Extension master
Tgr added a comment.Aug 20 2018, 12:01 PM

All extension properties depend on the extension version, so dealing with that should probably happen on a lower level (e.g. qualifiers if we go for the Wikibase option).

cicalese triaged this task as Medium priority.Jul 31 2019, 12:06 AM
cicalese moved this task from Inbox to Needs Discussion on the MediaWiki-Stakeholders-Group board.
Restricted Application added a subscriber: Liuxinyu970226. · View Herald TranscriptJul 31 2019, 12:06 AM