The upstream jQuery project is nearing a jQuery 4 release. No date has been announced yet, but I expect that similar to when we want from jQuery 1.x to jQuery 3.x that the migration phase of the previous transition must be completed first.
We upgraded to jQuery 3 in 2017 (T124742, T169385), and have been shipping the migrate plugin in its full form in the four years since then.
This task is for the planning, and progress tracking, of finishing off this transition, culiminating in the removal of the (current version of) the jquery-migrate plugin from MediaWiki core. I expect the vast majority of this transition to be a community endavour as I suspect that by now all WMF-deployed MediaWiki code to have updated any uses of it. Although it appears a few subtasks of T169385 did survive, so there may be a few of those as well.
Draft timeline
(Dates based on mw:Version lifecycle)
| When | Where | What |
|---|---|---|
| April 2017 | MediaWiki master branch + WMF | jQuery Migrate 3 introduced, on by default, with deprecation warnings. |
| July 2017 | MediaWiki 1.29.0 release | jQuery Migrate 3 introduced, on by default, with deprecation warnings. |
| … | … | … |
| April 2021 | MediaWiki master branch | $wgIncludejQueryMigrate is introduced, on by default, and deprecated. |
| May 2021 | MediaWiki 1.36.0 release | $wgIncludejQueryMigrate is introduced, on by default, and deprecated. |
| June 2021 | MediaWiki 1.35.3 LTS | $wgIncludejQueryMigrate is introduced, on by default (backport). |
| … | … | … |
| August 2021 | MediaWiki 1.37.0-alpha (CI) | $wgIncludejQueryMigrate is off by default. |
| September 2021 | MediaWiki 1.37.0-alpha (master branch) | $wgIncludejQueryMigrate is off by default. |
| TBD | MediaWiki 1.37.0-alpha (WMF) | $wgIncludejQueryMigrate is off by default. |
| November 2021 | MediaWiki 1.37.0 release | $wgIncludejQueryMigrate is off by default. |
| … | … | … |
| TBD | MediaWiki 1.38.0-alpha (master branch) | $wgIncludejQueryMigrate is removed. |
| May 2022 | MediaWiki 1.38.0 release | $wgIncludejQueryMigrate is removed. |
Draft roadmap
- Implement $wgIncludejQueryMigrate as temporary site configuration for enabling jQuery Migrate.
This will be similar to T46740, and be deprecated on-arrival, and true by default for 1 release, and then false by default until we're ready to remove it (hopefully within one or two release cycles).
Given it's a trivial boolean configuration that doesn't affect anything, it might even be viable to backport this to MW 1.35 and MW 1.36 so as to offer third-parties to disable this if they think they're already ready for it. (Depending on when MW 1.36 is out and when we land the option, we might not count that toward the 1 release, though).
- Disable $wgIncludejQueryMigrate in WMF CI
This should be trivial to do on short notice. The number of uses of deprecated jQuery methods is very low in our code base, but quite possibly zero if we only look at code covered by unit tests.
- Disable $wgIncludejQueryMigrate in master (and thus Beta Cluster), and enable explicitly in prod for group1 and group2.
Once disabled on Beta Cluster, it's probably a good time to send out reminders through Tech-News about updating gadgets, site scripts and user scripts if you notice jQuery deprecation warnings. And that if you're unsure, you can try things on test.wikipedia.org, test2.wikipedia.org, mediawiki.org or on the Beta Cluster (if it works there, you're done). In this announcement we can also offer communities to oppertunity to opt-in to disabling jQuery Migrate earlier (and thus be able to easily turn it back on while they're ahead of the curve).
- Disable $wgIncludejQueryMigrate on group1.
- Disable $wgIncludejQueryMigrate on group2.
Progress
Grafana: mw-js-deprecate / jQuery Migrate Hard-deprecation.
- jqXHR.success(), jqXHR.error(), jqXHR.complete().
- $.ajax() with cross-domain url to executable JSON-P response and no dataType: "script" option set.
- .removeAttr() for setting DOM properties to false. (Global Search: Project+MW, Global Search: User)
- .toggleClass() with no args, which inverses all internally memorized classes.
- .toggleClass(Boolean), which restored internally memorized classes.
- $obj.context and $obj.selector internal properties of jQuery objects.
- .size().
- $.swap().
- $.buildFragment().
- $.domManip().
- .data() names that contain dashes instead of camelCase.
- .load(), .unload(), and .error().
- .on("ready", fn).
- $.event.props, $.event.fixHooks.
- .offset() on invalid DOM element.
- $("#") and .find("#") were silently tolerated despite being invalid selectors.
- .andSelf().
Some features mentioned in the upgrade guide are omitted from the above list. Either because they do not require migration at this time, or because they have no polyfill in the migrate plugin and were already broken/migrated when we upgraded to jQuery 3 in 2017, or because they only affect older browsers where MediaWiki disables its JavaScript layer.
For example, methods that were deprecated in subsequent 3.x releases for possible removal in 4.0 naturally still exist in jQuery 3.6 and thus will work even without migrate plugin (they might come back as warnings in the jQuery Migrate 4).
