jQuery update strategy
WordPress is moving forward with a roadmap for updating its shipped version of jQuery and the jquery-migrate polyfill that has historically provided backward compatibility. See https://make.wordpress.org/core/2020/06/29/updating-jquery-version-shipped-with-wordpress/
This change will almost certainly cause many regressions across plugins and themes that use jQuery on the Commons. We need a strategy to deal with this.
As a starting place, it might be helpful to distinguish between a couple different kinds of cases:
1. Some plugins and themes don't use jQuery at all.
2. Some of our most popular themes and plugins - things like Jetpack, for example - are well-maintained, and will receive upstream updates that ensure compatibility. It's very likely that these will be fixed before the relevant WP update, and we don't need to worry about them here on the Commons.
3. The majority of plugins and themes on the Commons are either poorly maintained or unmaintained. For those in this category that use jQuery, some will probably be OK even after the jQuery update.
4. The remaining plugins and themes will break in ways large and small.
As a first step, we should try to detect which plugins/themes use jQuery (eliminating those in category 1). This should be easy. From there, it would be nice if we had an automated tool for identifying - at least in a preliminary fashion - which themes/plugins will be negatively affected. (I assume that there's something akin to PHPCS for this purpose. Does anyone know of anything?) Once we have a list, we can make some decisions about next steps.
#1 Updated by Boone Gorges 9 months ago
- Target version changed from 1.18.0 to 1.19.0
An update from the WP core team on this process: https://make.wordpress.org/core/2020/11/05/updating-core-jquery-to-version-3-part-2/
After the 1.18 release I'll get started on identifying problematic plugins/themes, as outlined above.
#5 Updated by Boone Gorges 5 months ago
- Target version changed from 1.18.5 to 1.18.7
Pushing this off until the March release.
I'll summarize the plan I've sketched, which I shared with the dev team yesterday:
For the main site and bp-nelo, we can go ahead and fix all of the inconsistencies. See #13352.
For sites created after the 1.18.7 release, allow them to load the default jQuery 3.x. We should ensure that the basic configurations for new sites is compatible with the latest jQuery. See #14003.
For existing sites on the network, we will load the enable-jquery-migrate-helper plugin https://wordpress.org/plugins/enable-jquery-migrate-helper/ The plugin has various configuration options, and I propose we use it as follows:
1. Serve the default jQuery version from WP (3.x)
2. Allow the plugin to log deprecations or failures
3. Hide the plugin's UI from non-super-admins. This includes the admin bar item, the Dashboard admin notices, and the plugin setting panel.
4. Enable the 'Automatic downgrades' feature, which falls back to the older version of jQuery when a serious JS error is detected.
5. Build a tool that logs sites that have (a) fallen back to older jQuery, and (b) logged deprecated notices.
For the days and weeks following the release, we will monitor the log from 5 on a regular basis. We'll decide what to do about these errors on a case-by-case basis. Those that are triggered by our first-party tools, or plugins that we maintain or have a connection to (such as BuddyPress), can be repaired. Others we may decide to report upstream. Some we can safely ignore.
As for the technical aspects of this, I will likely build a custom loader that will bootstrap the enable-jquery-migrate-helper plugin only when needed (on sites created before the 1.18.7 release), rather than network activating it and then figuring out a way to turn it off for sites where it's not needed. Some of items 1-5 can be accomplished by filtering the plugin settings (1, 2, 4, and some parts of 3). Some custom code may be required for parts of 3, particularly the hiding of the Dashboard panel and nav menu item. Item 5 will require a custom tool, and I'd like to make it modest. But it also needs to be non-noisy, and I think all it needs to contain is a list of sites that need checking, possibly split into two categories ("has fallen back to older jQuery" and "has logged deprecated notices"). I think this means one or two arrays of site IDs saved in the network options table, and I'll build a simple WP-CLI script that can be used to print a list of affected URLs.
I'll spend some time putting this together over the upcoming days. In the meantime, I welcome feedback on this plan.
#6 Updated by Boone Gorges 5 months ago
Here's a first pass at the custom logging functionality: https://github.com/cuny-academic-commons/cac/blob/3d1b1e4cb5c3dcdedb3f5be756d8e4eb40e6a48e/wp-content/mu-plugins/jquery-migrate.php Some implementation notes:
- Instead of building a logging tool, I'm just hijacking the email that the plugin sends out, having them sent to me instead. I'm hopeful that the numbers will be fairly limited.
- I'm doing nothing with deprecation notices at the moment, only automatic-downgrade, which is what happens when the plugin detects an error that stops JS execution
If and when the downgrade messages roll in, I'll have to do some cowboy coding to figure out the nature of the errors and the appropriate fixes, and then I'll reset the downgrade flag on a per-site basis.
#7 Updated by Jeremy Felt 4 months ago
I spent a little time checking out Wikimedia's eslint-plugin-no-jquery rules (https://github.com/wikimedia/eslint-plugin-no-jquery) for eslint against the Commons codebase (wp56 branch) to see how things looked.
You can generate HTML reports from eslint, so I've included two HTML files in that repo with the current state. If this data seems to be useful, then we can probably get eslint to output a CSV or something friendlier for manipulation via code. I'm attaching those files to this ticket to make them readily accessible.
I have not yet spent any time actually looking into the results and determining how actionable things are.
#8 Updated by Boone Gorges 4 months ago
- Target version changed from 1.18.7 to 1.18.8
Awesome! Thanks for working on this!
I've just begun to glance at the results, and I have a few initial thoughts:
- There are some false-positives related to ES6 syntax. For example, we see an error "Parsing error: The keyword 'const' is reserved" for wp-content/plugins/cac-courses/assets/js/app.js. But this file uses ES6 syntax, and is never in fact loaded in the production app; we load the built file instead. I don't know if this means that we should skip files like this, or that we should expand the eslint definition to allow ES6 syntax. It probably depends on the specific case. The numbers are small enough that we may be able to look at each case (I see a couple dozen of the hundreds of errors coming from similar cases in custom CAC plugins, for example, which we could definitely add to the ignore list)
- Some parse errors are in plugins/themes that are no longer available on the Commons (not network enabled, or filtered via mu-plugins/cac-functions.php). So we should safely be able to skip those as well, or at least handle them later on.
- I realize that we may not be able to scan minimized files for technical reasons, but this will probably cause us to miss legitimate errors.
The good news is that I don't see anything in the results that suggest we should hold off on our jQuery update strategy, which involves going to the latest WP as of today. I'll bump this ticket to the next milestone so that we can use it to track ongoing issues after the release.
#10 Updated by Boone Gorges 4 months ago
Since yesterday's release, I've received about five automatic-downgrade emails. For some reason, the plugin isn't properly logging the errors (maybe it only does this for deprecations, not for fatals?). But I was able to cross-reference the timestamps on the emails with the access log. And in each case, the downgrade was triggered by someone previewing an old theme in the Customizer: ArtSee, eNews, Bluemist.
These are all Elegant Themes products. Looking over their site, it appears that they've recently updated these themes to fix the incompatibilities. I'm going to run these upgrades and deploy the updates as hotfixes, so that further sites don't send me notices and improperly downgrade their jQuery. Then, because the themes are described as "legacy" by Elegant Themes, I plan to network-disable them on the Commons.
#12 Updated by Boone Gorges 4 months ago
Elegant Themes updates:
These changes have been pushed to the production site.
I've also network-disabled the themes, so they can no longer be activated (or previewed).