Page MenuHomePhabricator

Phase out jQuery Migrate v3
Open, MediumPublic

Description

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)

WhenWhereWhat
April 2017MediaWiki master branch + WMFjQuery Migrate 3 introduced, on by default, with deprecation warnings.
July 2017MediaWiki 1.27.0 releasejQuery Migrate 3 introduced, on by default, with deprecation warnings.
April 2021MediaWiki master branch$wgIncludejQueryMigrate is introduced, on by default, and deprecated.
TBDMediaWiki 1.35.x LTS$wgIncludejQueryMigrate is introduced, on by default (backport).
May 2021MediaWiki 1.36.0 release$wgIncludejQueryMigrate is introduced, on by default, and deprecated.
TBDMediaWiki 1.37.0-alpha (CI)$wgIncludejQueryMigrate is off by default.
TBDMediaWiki 1.37.0-alpha (master branch)$wgIncludejQueryMigrate is off by default.
TBDMediaWiki 1.37.0-alpha (WMF)$wgIncludejQueryMigrate is off by default.
November 2021MediaWiki 1.37.0 release$wgIncludejQueryMigrate is off by default.
TBDMediaWiki 1.38.0-alpha (master branch)$wgIncludejQueryMigrate is removed.
May 2022MediaWiki 1.38.0 release$wgIncludejQueryMigrate is removed.
Draft roadmap
  1. 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).

  1. 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.

  1. 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).

https://jquery.com/upgrade-guide/3.0/
https://jquery.com/upgrade-guide/3.5/

  1. Disable $wgIncludejQueryMigrate on group1.
  1. Disable $wgIncludejQueryMigrate on group2.
Progress
  • 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).

Event Timeline

Restricted Application added a subscriber: Aklapper. · View Herald Transcript

The good news is that almost all jQuery 3 deprecations are whole methods (and usually with trivial replacements). This means we can use Global Search and Codesearch to our advantage, as well as leverage automation like Tourbot.

Depending on how we do this, and how likely certain methods are to be beyond reach of search, we could also take an iterative approach and actually start janking out parts of the Migrate code once we've addressed all usage of that particular method. We can also update the mw.track instrumentation like we did at T46740 (right now we count "jquery-migrate" as one thing in mw-js-deprecate, but we could instead make it count things like jquery-migrate.isNumeric, jquery-migrate.isFunction, etc.

Change 522569 had a related patch set uploaded (by Krinkle; author: Jforrester):

[mediawiki/core@master] Drop $j alias for $, deprecated since 1.23

https://gerrit.wikimedia.org/r/522569

Change 682228 had a related patch set uploaded (by Krinkle; author: Krinkle):

[mediawiki/core@master] jquery: Add method/prop name to jquery_migrate deprecation counter

https://gerrit.wikimedia.org/r/682228

Change 682229 had a related patch set uploaded (by Krinkle; author: Krinkle):

[mediawiki/core@master] resourceloader: Add $wgIncludejQueryMigrate option

https://gerrit.wikimedia.org/r/682229

Change 682229 merged by jenkins-bot:

[mediawiki/core@master] resourceloader: Add $wgIncludejQueryMigrate option

https://gerrit.wikimedia.org/r/682229

Change 682221 had a related patch set uploaded (by Jforrester; author: Krinkle):

[mediawiki/core@REL1_36] resourceloader: Add $wgIncludejQueryMigrate option

https://gerrit.wikimedia.org/r/682221

Change 682221 merged by jenkins-bot:

[mediawiki/core@REL1_36] resourceloader: Add $wgIncludejQueryMigrate option

https://gerrit.wikimedia.org/r/682221

Change 682264 had a related patch set uploaded (by Krinkle; author: Krinkle):

[mediawiki/core@REL1_35] resourceloader: Add $wgIncludejQueryMigrate option

https://gerrit.wikimedia.org/r/682264

Change 682264 merged by jenkins-bot:

[mediawiki/core@REL1_35] resourceloader: Add $wgIncludejQueryMigrate option

https://gerrit.wikimedia.org/r/682264

Change 682228 merged by jenkins-bot:

[mediawiki/core@master] jquery: Add method/prop name to jquery_migrate deprecation counter

https://gerrit.wikimedia.org/r/682228

The detailed stats are now in:
https://grafana.wikimedia.org/d/000000037/mw-js-deprecate?orgId=1&refresh=1m&from=now-30d&to=now

capture.png (1×2 px, 135 KB)

First panel is breaking changes and hard deprecations that require the Migrate plugin, second panel is soft deprecations.

The checkboxes in this task's summary track the former. Looks like we're doing okay overall.

Completed: $.domManip().

  • Live deprecation stats from sampled users: none.
  • Global on-wiki search: none (except for false-positive matches in copies of jquery.js).
  • Codesearch: none (except for false-positive matches in copies of jquery.js).

Completed: $.buildFragment().

  • Live deprecation stats from sampled users: already zero.
  • Codesearch: already zero (except for false-positives in jquery.js).
  • Global on-wiki search: fix last one (remainder is false hits from jquery.js copies).

Completed: $.event.props, $.event.fixHooks.

I'm cleaning up removeAttr now.

Change 703475 had a related patch set uploaded (by Ladsgroup; author: Ladsgroup):

[mediawiki/core@master] Set $wgIncludejQueryMigrate to false in CI/dev

https://gerrit.wikimedia.org/r/703475

Change 703476 had a related patch set uploaded (by Ladsgroup; author: Ladsgroup):

[operations/mediawiki-config@master] Set $wgIncludejQueryMigrate to false in group0

https://gerrit.wikimedia.org/r/703476

The hard deprecations are small in size and really hard to fix. For example, I went through andSelf and basically every case was the user copying the whole jquery library.

I suggest we communicate and drop the migrations and then fix if any major user gadget break (which I doubt as the number is pretty low).

Krinkle updated the task description. (Show Details)

Fixing of user scripts is optional, and always has been. Any easy find/replace actions that we can do semi-automatically, I've generally tried to do, but beyond that it's best-effort, and certain no need to contact each individual author. Our standard communication channels for this are the developer console, Tech News, wikitech-ambassadors, wikitech-l, and release notes.

However, use in MW core and deployed extensions does need to be completed before we can turn off migrate.

Change 703627 had a related patch set uploaded (by Ladsgroup; author: Ladsgroup):

[mediawiki/core@master] [WIP] Patch jquery.ui to reduce deprecation warnings

https://gerrit.wikimedia.org/r/703627

Change 703876 had a related patch set uploaded (by Ladsgroup; author: Ladsgroup):

[data-values/value-view@master] Fix jquery upgrade deprecations

https://gerrit.wikimedia.org/r/703876

Change 703877 had a related patch set uploaded (by Ladsgroup; author: Ladsgroup):

[mediawiki/extensions/UniversalLanguageSelector@master] Fix jquery deprecation

https://gerrit.wikimedia.org/r/703877

Change 703877 merged by jenkins-bot:

[mediawiki/extensions/UniversalLanguageSelector@master] Fix jquery deprecation

https://gerrit.wikimedia.org/r/703877

Change 703876 merged by jenkins-bot:

[data-values/value-view@master] Fix jquery upgrade deprecations

https://gerrit.wikimedia.org/r/703876

Change 704075 had a related patch set uploaded (by Ladsgroup; author: Ladsgroup):

[mediawiki/extensions/Wikibase@master] Bump javascript submodules (only jquery ones) to HEAD

https://gerrit.wikimedia.org/r/704075

Change 704075 merged by jenkins-bot:

[mediawiki/extensions/Wikibase@master] Bump javascript submodules (only jquery ones) to HEAD

https://gerrit.wikimedia.org/r/704075

After these patches wikidata in beta cluster went from this:

image.png (228×561 px, 45 KB)

to this:
image.png (185×523 px, 36 KB)

The core patch will improve even more but regardless we will see a big drop in mw-js-deprecate metrics this week.

Change 703627 merged by jenkins-bot:

[mediawiki/core@master] Patch jquery.ui to reduce deprecation warnings

https://gerrit.wikimedia.org/r/703627

Now

image.png (151×643 px, 24 KB)

I think there are some left when you try to edit etc. I'll be one it next week.

Change 704571 had a related patch set uploaded (by Ladsgroup; author: Ladsgroup):

[mediawiki/core@master] Fix most of jquery.ui deprecations

https://gerrit.wikimedia.org/r/704571

Change 704571 merged by jenkins-bot:

[mediawiki/core@master] Fix most of jquery.ui deprecations

https://gerrit.wikimedia.org/r/704571

Change 708250 had a related patch set uploaded (by Ladsgroup; author: Ladsgroup):

[data-values/value-view@master] Fix jquery deprecation

https://gerrit.wikimedia.org/r/708250

Change 708250 merged by jenkins-bot:

[data-values/value-view@master] Fix jquery deprecation

https://gerrit.wikimedia.org/r/708250

Change 708284 had a related patch set uploaded (by Ladsgroup; author: Ladsgroup):

[mediawiki/extensions/Wikibase@master] Bump wikibase-data-values-value-view to HEAD

https://gerrit.wikimedia.org/r/708284

Change 708284 merged by jenkins-bot:

[mediawiki/extensions/Wikibase@master] Bump wikibase-data-values-value-view to HEAD

https://gerrit.wikimedia.org/r/708284