-
Notifications
You must be signed in to change notification settings - Fork 98
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Upgrade: add 4.0 upgrade guide #250
base: main
Are you sure you want to change the base?
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
A good first draft! I added some comments.
|
||
#### Breaking change: JSON to JSONP auto-promotion removed | ||
|
||
Previously, `jQuery.ajax` with `dataType: 'json'` with a provided callback was automatically converted to a JSONP request unless one also specified `jsonp: false`. Today, the preferred way of interacting with a cross-domain backend is CORS, which works in all browsers jQuery 4 supports. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Let's use the jQuery style guide in code samples which means double quites:
Previously, `jQuery.ajax` with `dataType: 'json'` with a provided callback was automatically converted to a JSONP request unless one also specified `jsonp: false`. Today, the preferred way of interacting with a cross-domain backend is CORS, which works in all browsers jQuery 4 supports. | |
Previously, `jQuery.ajax` with `dataType: "json"` with a provided callback was automatically converted to a JSONP request unless one also specified `jsonp: false`. Today, the preferred way of interacting with a cross-domain backend is CORS, which works in all browsers jQuery 4 supports. |
You've actually already used double quotes on a similar example below.
|
||
To fetch *and* evaluate a script, pass `dataType: "script"` in `jQuery.ajax` options or use `jQuery.getScript`. | ||
|
||
#### Breaking change: Script tags now used for all async requests |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
...except for some JSONP scripts. But maybe conceptually JSONP is separate from script even though it's using the same infra underneath? What do you think? Is it worth mentioning it here or would it just be confusing?
|
||
### Attributes | ||
|
||
#### Breaking change: `toggleClass(boolean | undefined)` signature removed |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Code style + we've used uppercase types so far in similar texts:
#### Breaking change: `toggleClass(boolean | undefined)` signature removed | |
#### Breaking change: `toggleClass( Boolean | undefined )` signature removed |
* `jQuery.isArray` | ||
* `jQuery.isFunction` | ||
* `jQuery.isNumeric` | ||
* `jQuery.isWindow` | ||
* `jQuery.fx.interval` | ||
* `jQuery.parseJSON` | ||
* `jQuery.nodeName` | ||
* `jQuery.now` | ||
* `jQuery.trim` | ||
* `jQuery.type` |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Let's document them all - although I'm fine with doing it in a separate PR. You can always start with relevant entries from https://github.com/jquery/jquery-migrate/blob/main/warnings.md.
Also, with so many entries, maybe it'd be better to dedicate a small section to each of them, with a separate header as in the toggleClass
case above.
|
||
#### Important fix: `Object.prototype` pollution | ||
|
||
jQuery 4.0 includes a fix to ensure event and data keys matching `Object.prototype` properties are supported without overriding the native properties. This change is not expected to affect existing code unless it specifically used native property names as event or data keys, which may have caused unexpected behavior anyway. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is no the only case of a breaking change; I'd even argue it's a less common one. Even more so, now keys matching Object.prototype
keys should just work so it's hard for me to imagine what could break in this case.
The case that breaks is if someone used .data()
to get the whole data object and then e.g. called hasOwnProperty
on it.
|
||
The slim build of jQuery 4.0 no longer includes the `callbacks` and `deferred` modules. Use the full build if you need these modules, or use native Promise objects. | ||
|
||
#### Breaking change: Remove undocumented `root` parameter of `jQuery()` |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Not of jQuery()
; of jQuery.fn.init()
. jQuery
is already skipping this argument even on 3.x-stable
(https://github.com/jquery/jquery/blob/3.x-stable/src/core.js#L33-L38):
jQuery = function( selector, context ) {
// The jQuery object is actually just the init constructor 'enhanced'
// Need init if jQuery is called (just allow error to be thrown if not included)
return new jQuery.fn.init( selector, context );
};
while in jQuery.fn.init
it exists there (https://github.com/jquery/jquery/blob/3.x-stable/src/core/init.js):
init = jQuery.fn.init = function( selector, context, root ) {
Let's also mentioned this is the third parameter.
|
||
jQuery exports multiple builds that can be used in different environments. This includes the default build as both a universal module (UMD) and an ESM module, the slim build in UMD and ESM, and a factory build for running jQuery with DOM emulators like JSDOM. The `exports` field in `package.json` is used to specify which build is used in different environments. This change is not expected to affect existing code. | ||
|
||
### CSS |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
From my summary:
* CSS: Remove the opacity CSS hook
* 865469f5e60f55feb28469bb0a7526dd22f04b4e
* The consequence is `.css( "opacity" )` will now return an empty string for detached elements in standard-compliant browsers and "1" in IE & the legacy Edge. That behavior is shared by most other CSS properties which we're not normalizing either.
Let's mention that now .css( "opacity" )
on disconnected elements will return an empty string instead of "1"
in modern browsers. I expect some code may depend on the "1"
default.
|
||
Instead, jQuery will now only add `px` to a limited set of properties that are known to require it. This change may affect existing code that relies on the old behavior. | ||
|
||
### Data |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'd mention that the .data()
setter used to convert -ms-x
to msX
and now to MsX
. This is a result of separating camelCase
logic between data
& css
modules.
|
||
The recommendation for migration is to be explicit about which classes should be toggled. | ||
|
||
### Core |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Some people used our AMD modules directly; I'd mention that jQuery source is now authored using ESM and code under src/
is in ESM.
What's cool is that it works natively in the browser as well. You can just do - assuming you have jQuery cloned into the folder jquery
next to the HTML file, or downloaded from npm:
<script type="module">
import { $ } from "./node_modules/jquery/src/jquery.js";
/* ... */
</script>
or, using import maps:
<script type="importmap">
{
"imports": {
"jquery": "./jquery/src/jquery.js"
}
}
</script>
<script type="module">
import { $ } from jquery";
/* ... */
</script>
and it works without any build process while importing all the individual jQuery modules natively. Of course, you can also import our built module file:
<script type="importmap">
{
"imports": {
"jquery": "./node_modules/jquery/dist-module/jquery.module.js"
}
}
</script>
<script type="module">
import { $ } from jquery";
/* ... */
</script>
It's pretty cool that it works, I'd mention it with some examples.
|
||
For a complete and detailed list of all code changes, see the 3.0 milestone in the [jQuery Core issue tracker](https://github.com/jquery/jquery/issues?q=is%3Aissue+milestone%3A4.0.0) or the [version diff](https://github.com/jquery/jquery/compare/3.7.1...4.0.0). | ||
|
||
### Ajax |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Should we mention Ajax now supports binary data in bodies - the minor breaking change is that prefilters are now fired a bit earlier, before converting the body to a string? This is a pretty important feature.
I know some of that may only make sense in the blog post. But there's a small breaking change attached here.
Fixes jquery/jquery#5365