Support only the 3.x release of jQuery Core

[dmethvin]

As of jQuery Migrate 3.0, this plugin should be paired only with Core 3.x and not older versions. That simplifies the work the plugin needs to do since it can depend on the behavior and APIs of the latest core and not have to work around all the quirks of previous versions.

• Document this new usage in the README, which is to include the latest Core and Migrate in the old project. (Previously, we would tell users to include Migrate with the current version of Core they were using on the page.)
• Add a version check to ensure people don't misuse 3.0 by running it with older versions of jQuery.
• Update Migrate code to remove any Core-version-dependent code paths, for example the checks whether internal functions are privatized
• Determine and document the Core versions that we support for doing an upgrade. Presently it's 1.6.4 but this approach may make it possible to go back further?

[mgol]

One thing to think about is that Migrate restoring behavior from 1.6.4 (or older) may make it harder for people to update from newer versions. If someone just wanted to aid the upgrade process from 1.8 to 3.0.0 Compat then restoring the old .attr/.prop semantics is only going to hurt.

If Migrate continued supporting older versions, one way to upgrade would be to not change the .attr/.prop behavior but to warn if used in a probably incorrect way so that people can:

1. Use an old jQuery.
2. Add a Migrate to it, fix warnings.
3. Update jQuery, fix warnings.
4. Remove Migrate.

Now the process will have to look like:

1. Use an old jQuery.
2. Update jQuery & add a Migrate to it, fix warnings.
3. Remove Migrate.

We need to think how to accommodate both people updating from 1.6.4 and ones updating from 1.9.

[dmethvin]

I agree there are some behavior changes to existing APIs that can get tricky here, the .attr/.prop being the most painful. When we first did Migrate the odds were that old code would need every shim and therefore it was handy to have Migrate "fix" everything back to the old way so that old code could continue to work. Now there is a higher chance that people may be mixing plugins that depend on different (and possibly conflicting) jQuery behavior.

We need to look at the most common scenarios where people might be applying Migrate and see how we can address them. I still think the "just fix it" crowd will be a large part of the usage, so replacing working shims with just a warning doesn't work for those cases.

Maybe it makes sense to break out some of the more controversial parts somehow and only activate them on request?

[mgol]

Brainstorming: how about a "upgradingFrom" option (without going into details how it would be activated) that would, e.g., restore the previous .prop/.attr behavior if set to "1.6" and wouldn't touch it if set to "1.9"? We don't have to restore every change, just ones that have high enough chance to break people's sites.

[gibson042]

jQuery Migrate currently appears to have an identity disorder. When loaded on an "old" jQuery, it tries to warn about deprecated/abandoned behavior. Otherwise, it tries to restore those behaviors, with warnings. The problem is that some cases may lack clarity around which old behavior to restore. So in my opinion it makes sense to bind together major versions of the two libraries (hence this issue), but there are two ways to do it:

Forward over an old jQuery
The next jQuery Migrate release warns about backwards incompatibility (e.g., $el.data("dashed-key") when a "dashed-key" datum exists) and optionally updates behavior to match jQuery 3.

Usage:

1. Load jQuery Migrate
2. Address warnings
3. Update to new behavior, either by jumping straight to a new jQuery (Migrate would be harmless to keep around for warnings, but might not be useful) or by an intermediate step in which Migrate is trusted to monkey-patch behavior forward (which is valuable when Migrate has known gaps, as is currently the case)

Backward over a current jQuery
The next jQuery Migrate release warns about backwards incompatibility and optionally updates behavior to match jQuery 1.x/2.x.

Usage:

1. Replace jQuery 1.x/2.x with jQuery 3 plus a behavior-restoring jQuery Migrate (requires all application-significant behavior to be monkey-patched)
2. Address warnings
3. Disable behavior restoration, either by dropping Migrate or by an intermediate step in which monkey-patching is disabled

I talked myself into the second in a private conversation, partly on the basis of assuming that most migrations would be from 1.x/2.x, but had not fully considered separating warnings from monkey-patches as a proper concept. In light of the above, I think I have to reverse that preference—the first option is both closer to our current strategy and more tolerant of a jQuery Migrate development lag (but for that matter, it also makes it easier to pick changes nearly verbatim from jQuery proper). It's also likely more palatable for consumers.

The pattern we'd drop is running a new jQuery with its backwards-monkey-patching Migrate partner to present an old API but warn about its misuse, instead directing people to use the jQuery they already have and let Migrate help it present a newer API when they're ready.

There's also the question of version numbering: assuming the forward model, would we want jQuery 1.x/2.x to be partnered with Migrate 2 or Migrate 3, given that the warnings and behaviors would be tied to jQuery 3 but minimum supported versions would probably be 1.10/2.0 (or jQuery <1.10 plus Migrate 1.2)?