Page MenuHomePhabricator

Phase out jQuery Migrate v3
Closed, ResolvedPublic

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.29.0 releasejQuery Migrate 3 introduced, on by default, with deprecation warnings.
April 2021MediaWiki master branch$wgIncludejQueryMigrate is introduced, on by default, and deprecated.
May 2021MediaWiki 1.36.0 release$wgIncludejQueryMigrate is introduced, on by default, and deprecated.
June 2021MediaWiki 1.35.3 LTS$wgIncludejQueryMigrate is introduced, on by default (backport).
August 2021MediaWiki 1.37.0-alpha (CI)$wgIncludejQueryMigrate is off by default.
September 2021MediaWiki 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).

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

Details

ProjectBranchLines +/-Subject
mediawiki/coreREL1_37+2 -9
mediawiki/coremaster+2 -9
mediawiki/coremaster+4 -870
operations/mediawiki-configmaster+0 -1
operations/mediawiki-configmaster+2 -6
operations/mediawiki-configmaster+1 -0
operations/mediawiki-configmaster+2 -0
operations/mediawiki-configmaster+2 -0
operations/mediawiki-configmaster+1 -0
mediawiki/coremaster+4 -4
operations/mediawiki-configmaster+4 -0
operations/mediawiki-configmaster+4 -0
mediawiki/coremaster+21 -4
mediawiki/coreREL1_36+21 -4
mediawiki/coreREL1_35+22 -4
mediawiki/coremaster+3 -0
mediawiki/coremaster+35 -34
mediawiki/extensions/DiscussionToolsmaster+0 -9
mediawiki/extensions/Wikibasemaster+1 -1
data-values/value-viewmaster+1 -1
mediawiki/coremaster+18 -20
mediawiki/coremaster+45 -39
mediawiki/extensions/Wikibasemaster+4 -4
data-values/value-viewmaster+22 -21
mediawiki/extensions/UniversalLanguageSelectormaster+1 -1
mediawiki/coremaster+65 -170
Show related patches Customize query in gerrit

Related Objects

Event Timeline

There are a very large number of changes, so older changes are hidden. Show Older Changes

Change 710666 merged by jenkins-bot:

[mediawiki/core@master] jquery.ui: Patch more jquery 3 fixes

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

Hi. I'd like to know when specifically this should be included in Tech News, and what specifically the blurb should say.
I know Ladsgroup recently sent the email to wikitech-l ("Phasing out old jQuery versions") explaining some of the details.

When? -- I don't know.

What? -- IIUC, the blurb should say something like this... (please rewrite/tweak as needed!)

(Section: "Future changes")
Gadget and code maintainers should check that they have fixed any JQMIGRATE errors. Very old gadgets might break if they are not fixed. The 4 year old backward compatibility layer is going to be removed on [DATE?] to improve site-loading performance for everyone. Information about how to find and fix these errors is in [LOCATION-LINK?]

(Re: "location-link" -- if there isn't already an onwiki page which covers it, then I'd also suggest that someone adds the details on how to "find and fix" into the very-top of this task's Description, for easy discoverability)
Thanks!

Hi. I'd like to know when specifically this should be included in Tech News, and what specifically the blurb should say.
I know Ladsgroup recently sent the email to wikitech-l ("Phasing out old jQuery versions") explaining some of the details.

When? -- I don't know.

I'm not sure yet, specially I want the new set of fixes of jquery.ui to go out so I could see the impact and likely afterwards we can put it in tech news.

What? -- IIUC, the blurb should say something like this... (please rewrite/tweak as needed!)

(Section: "Future changes")
Gadget and code maintainers should check that they have fixed any JQMIGRATE errors. Very old gadgets might break if they are not fixed. The 4 year old backward compatibility layer is going to be removed on [DATE?] to improve site-loading performance for everyone. Information about how to find and fix these errors is in [LOCATION-LINK?]

Is there a way to emphasize that not all JQMIGRATE will break (but some will?)

(Re: "location-link" -- if there isn't already an onwiki page which covers it, then I'd also suggest that someone adds the details on how to "find and fix" into the very-top of this task's Description, for easy discoverability)

I couldn't find one, this ticket seems the right place (I checked https://www.mediawiki.org/wiki/ResourceLoader/Migration_guide_(users) and nothing useful was there). Maybe @Krinkle knows a better guide.

Some jquery.ui fixes have been deployed now. @MaxSem Can you check your gadgets to see if it got better or not?

Since some fixes have been deployed, is there anything to announce to communities? I'm asking since this task has the user-notice tag.

If there is something communities should be aware of, can someone write a quick summary before tomorrow 15:00 UTC? Thank you!

  • .size()

Used tourbot to semi-automatically fixup uses in user scripts where the context was obviously a jQuery object (e.g. variable is named with a dollar sign and has other known jQuery methods called on it within the diff context, or the call host is visibly the result of calling $()), and audited the remaining 30 results to be false positives.

The Grafana: mw-js-deprecate / jQuery Hard-deprecation graph shows mainly three deprecated features still in use, which are also among the hardest to proactively find through search alone.

  • html_xhtmlTag
  • ajax_jsonp_auto
  • load

I've given these three special attention in Migration guide § jQuery Migrate 3 on mediawiki.org.

@Trizek-WMF Thanks, not yet. I think next week perhaps.

A rough plan:

  • Next week: Turn it off on beta and group0
  • The week after (06 September): Early adapter wikis and volunteers.
  • Several weeks later: Turn off everywhere
  • For 1.37: Default would be false
  • For 1.38: The whole migration file removed.

Change 715324 had a related patch set uploaded (by Ladsgroup; author: Amir Sarabadani):

[operations/mediawiki-config@master] beta: Set $wgIncludejQueryMigrate to false

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

Change 715325 had a related patch set uploaded (by Ladsgroup; author: Amir Sarabadani):

[mediawiki/core@master] Set $wgIncludejQueryMigrate to false as default

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

Change 715324 merged by jenkins-bot:

[operations/mediawiki-config@master] beta: Set $wgIncludejQueryMigrate to false

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

Change 703476 merged by jenkins-bot:

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

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

Mentioned in SAL (#wikimedia-operations) [2021-08-30T09:34:07Z] <ladsgroup@deploy1002> Synchronized wmf-config/InitialiseSettings.php: Config: [[gerrit:703476|Set $wgIncludejQueryMigrate to false in group0 (T280944)]] (duration: 00m 57s)

A rough plan:

  • Several weeks later: Turn off everywhere
  • For 1.37: Default would be false

These two will have to be the other way around chronologically; the 1.37.0 cut is in two weeks' time. We're going to want to switch the default setting essentially now…

Change 715325 merged by jenkins-bot:

[mediawiki/core@master] Set $wgIncludejQueryMigrate to false as default

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

Can this be announced now? Thank you!

Change 719524 had a related patch set uploaded (by Ladsgroup; author: Amir Sarabadani):

[operations/mediawiki-config@master] Turn off jQuery migrate on wikisource wikis

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

Change 719524 merged by jenkins-bot:

[operations/mediawiki-config@master] Turn off jQuery migrate on wikisource wikis

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

Mentioned in SAL (#wikimedia-operations) [2021-09-08T16:28:47Z] <ladsgroup@deploy1002> Synchronized wmf-config/InitialiseSettings.php: Config: [[gerrit:719524|Turn off jQuery migrate on wikisource wikis (T280944)]] (duration: 00m 59s)

Krinkle updated the task description. (Show Details)

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

[operations/mediawiki-config@master] Early adopt wgIncludejQueryMigrate=false on nlwiki

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

Change 720387 merged by jenkins-bot:

[operations/mediawiki-config@master] Early adopt wgIncludejQueryMigrate=false on nlwiki

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

Mentioned in SAL (#wikimedia-operations) [2021-09-14T20:20:50Z] <ladsgroup@deploy1002> Synchronized wmf-config/InitialiseSettings.php: Config: [[gerrit:720387|Early adopt wgIncludejQueryMigrate=false on nlwiki (T280944)]] (duration: 01m 48s)

Change 721610 had a related patch set uploaded (by Ladsgroup; author: Amir Sarabadani):

[operations/mediawiki-config@master] Set jQuery migrate to false for wikibooks and Commons

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

Change 721610 merged by jenkins-bot:

[operations/mediawiki-config@master] Set jQuery migrate to false for wikibooks and Commons

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

Mentioned in SAL (#wikimedia-operations) [2021-09-16T20:49:08Z] <ladsgroup@deploy1002> Synchronized wmf-config/InitialiseSettings.php: Config: [[gerrit:721610|Set jQuery migrate to false for wikibooks and Commons (T280944)]] (duration: 00m 56s)

Change 722348 had a related patch set uploaded (by Ladsgroup; author: Amir Sarabadani):

[operations/mediawiki-config@master] Disable jQuery Migrate on group1

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

Change 722348 merged by jenkins-bot:

[operations/mediawiki-config@master] Disable jQuery Migrate on group1

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

Mentioned in SAL (#wikimedia-operations) [2021-09-20T11:18:08Z] <ladsgroup@deploy1002> Synchronized wmf-config/InitialiseSettings.php: Config: [[gerrit:722348|Disable jQuery Migrate on group1 (T280944)]] (duration: 00m 56s)

This morning's change has broken the CentralNotice UI: T291410

Let's revert it for a little while, and fundraising tech will try to get that widget updated ASAP.

Change 722348 merged by jenkins-bot:

[operations/mediawiki-config@master] Disable jQuery Migrate on group1

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

I reverted this after a request from ejegg and AndyRussG because of T291410: Central notice projects and language choices not loading. Once that's fixed it should be fine to retry. Or if we do all group1 except metawiki, AIUI that would be fine too.

Apologies, @Ladsgroup, others working on this, and thanks so much @Legoktm ! Please see T291410 and also T291431.

Change 722916 had a related patch set uploaded (by Ladsgroup; author: Amir Sarabadani):

[operations/mediawiki-config@master] Set jQuery migrate to false everywhere except metawiki

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

Change 722916 merged by jenkins-bot:

[operations/mediawiki-config@master] Set jQuery migrate to false everywhere except metawiki

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

Mentioned in SAL (#wikimedia-operations) [2021-09-22T16:13:46Z] <ladsgroup@deploy1002> Synchronized wmf-config/InitialiseSettings.php: Config: [[gerrit:722916|Set jQuery migrate to false everywhere except metawiki (T280944)]] (duration: 01m 56s)

Apologies, @Ladsgroup, others working on this, and thanks so much @Legoktm ! Please see T291410 and also T291431.

Hi, please let me know once the fix is in production so I can try it again.

Another breakage: .find("a[href^=#]") previously worked without # being surrounded with quotation marks at the CSS level, now only .find('a[href^="#"]') works (update to a gadget). It’s quite tricky to grep for…

Another breakage: .find("a[href^=#]") previously worked without # being surrounded with quotation marks at the CSS level, now only .find('a[href^="#"]') works (update to a gadget). It’s quite tricky to grep for…

Yeah, that's why I didn't proactively fix them as volunteer with my bot because it would have been too much work to check against all the correct ones.

I believe we can take some comfort in the potenetial impact, however. Some data:

  • This change to jQuery was applied to MediaWiki in 2017. I believe upstream jQuery did this to match the plain JavaScript behaviour as has always been the case in tutorials and manuals about browser JavaScript and DOM. For example document.querySelector("a[href^=#]") has always resulted in an error, even before 2017.
  • Since 2017, on any Wikimedia wiki, this selector with jQuery has reported the following warning in the browser console for any gadget maintainers to see:

JQMIGRATE: Attribute selector with '#' must be quoted: a[href^=#]

  • It is listed on mw:RL/MGU and an explaination can be found in the linked jQuery Migrate guide.
  • The anonymous counts we collected (Grafana: mw-js-deprecate) showed that on most days there were zero times where a logged-in user was online with a user script or gadget that used the invalid # selector. In some cases of the ~4000 entries during an entire day, there was 1 or sometimes up to 2.
Screenshot 2021-09-23 at 01.25.45.png (1×2 px, 120 KB)
Screenshot 2021-09-23 at 01.25.00.png (1×2 px, 46 KB)

I"m seeing various issues relating to scripts using load method instead of on('load', . It was showing up as TypeError: url.indexOf is not a function in our error logs.
e.g. https://meta.wikimedia.org/w/index.php?title=User%3ABrion_VIBBER%2Fmobile-sidebar.js&type=revision&diff=22062237&oldid=10185490

The main offender was a site-wide gadget on French Wikipedia which I've taken care of, but would be good to clean up the rest if possible.

I believe upstream jQuery did this to match the plain JavaScript behaviour as has always been the case in tutorials

While debugging the mentioned gadget, I found that it not only matches the plain JavaScript behaviour, it actually uses querySelectorAll() (with proper fallback I suppose), which is great, as C++ is probably more efficient than jQuery’s JS-only solution.

  • The anonymous counts we collected (Grafana: mw-js-deprecate) showed that on most days there were zero times where a logged-in user was online with a user script or gadget that used the invalid # selector. In some cases of the ~4000 entries during an entire day, there was 1 or sometimes up to 2.

Then something’s broken around the logging. What I’ve fixed is a default gadget, used on some of the busiest pages like administrators’ noticeboard or requests for deletions (through the template {{Fejléc}}). According to pageviews, select five pages had no day in the last twenty days that any of them had had zero pageviews; the average of the five was around 40 page views/page/day (although I think this is vastly underestimated, and the reality is much more; maybe pageviews counts only anonymous page views?). The error was thrown on page load, without any user interaction, so the number of page views should mostly correspond to the number of errors (warnings before the switch) thrown, barring some edge cases like users with JS disabled.

It has 1:100 sampling and only logged in users.

I'm going to repeat what I said in T72470: Remove legacy javascript globals:

Hi, Thanks for pointing out but let me be clear here. We are not going to fix all scripts users have been writing and using in all wikis. We try our best and more importantly make sure Common.js (and preferably all mediawiki namespace gadgets) are fixed but we can't possibly sweep millions of lines of code to find all of these and fix them. I personally did more 10K fixes just in the past months (More than 50K for all deprecation fixes) and this has been emitting warnings for more five years. We have communicated this in tech news but that's all.

We make sure not to roll out a huge change without proper deprecation warnings and communication and giving enough time to fix (which we did here) but fixing user scripts is responsibility of the maintainer not us.

This change objectively reduced 4KB from the default payload reducing at least hundreds of gigabytes everyday for our users.

@AndyRussG @Ejegg Hi, Am I clear to move forward with meta? Let me know please. Thanks!

@AndyRussG @Ejegg Hi, Am I clear to move forward with meta? Let me know please. Thanks!

Hi @Ladsgroup! Thanks for your patience. Yes, the fix now deployed to Meta (as of yesterday's train deploy), so everything should work now. Thanks again! :)

Change 725032 had a related patch set uploaded (by Ladsgroup; author: Amir Sarabadani):

[operations/mediawiki-config@master] Disable jQuery migrate in metawiki

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

Change 725032 merged by jenkins-bot:

[operations/mediawiki-config@master] Disable jQuery migrate in metawiki

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

Mentioned in SAL (#wikimedia-operations) [2021-09-30T16:11:57Z] <ladsgroup@deploy1002> Synchronized wmf-config/InitialiseSettings.php: Config: [[gerrit:725032|Disable jQuery migrate in metawiki (T280944)]] (duration: 01m 09s)

Change 725035 had a related patch set uploaded (by Ladsgroup; author: Amir Sarabadani):

[mediawiki/core@master] Drop jQuery migrate

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

Change 725035 merged by jenkins-bot:

[mediawiki/core@master] Drop jQuery migrate

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

Ladsgroup claimed this task.

This is done.

Change 522569 merged by jenkins-bot:

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

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

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

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

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

Change 726947 merged by jenkins-bot:

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

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