8000 Upgrade: add 4.0 upgrade guide [wip] [skip ci] · timmywil/jquery.com@d2e8977 · GitHub
[go: up one dir, main page]
Skip to content

Commit d2e8977

Browse files
timmywiltimmywil
committed
Upgrade: add 4.0 upgrade guide [wip] [skip ci]
Fixes jquery/jquery#5365
1 parent 323abad commit d2e8977

File tree

3 files changed

+119
-1
lines changed

3 files changed

+119
-1
lines changed

‎pages/upgrade-guide.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,8 @@
77

88
The jQuery upgrade guides provide information on all breaking changes and some notable changes in pinnacle versions of jQuery. Overall, jQuery has had very strong backwards compatibility throughout its history. However, these breaking changes were deemed necessary to address security concerns, fix bugs that could not be fixed without behavior changes, or to adapt to the introduction of modern APIs on the web. Most of the breaking changes listed should not apply to the majority of users, but these guides add some context and explanation for each change.
99

10+
### [4.0 Upgrade Guide](/upgrade-guide/4.0/)
11+
1012
### [3.5 Upgrade Guide](/upgrade-guide/3.5/)
1113

1214
### [3.0 Upgrade Guide](/upgrade-guide/3.0/)

‎pages/upgrade-guide/3.0.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,7 @@ Changes are listed by their component category, and prefixed with a description
5252

5353
Remember that the jQuery Migrate plugin described above can detect and warn about many of these changes so that they can be fixed in your code.
5454

55-
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%3Aopen+is%3Aissue+milestone%3A3.0.0) or the [version diff](https://github.com/jquery/jquery/compare/2.2-stable...master).
55+
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%3A3.0.0) or the [version diff](https://github.com/jquery/jquery/compare/2.2.4...3.0.0).
5656

5757
### Ajax
5858
#### Breaking change: Special-case Deferred methods removed from jQuery.ajax

‎pages/upgrade-guide/4.0.md

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
<script>{
2+
"title": "jQuery Core 4.0 Upgrade Guide",
3+
"toc": true
4+
}</script>
5+
6+
## Overview
7+
8+
With the major version of 4.0, the jQuery Core team has taken the opportunity to make changes to clean up the API and fix bugs that may prove to be breaking changes for some code. This includes the removal of previously deprecated public APIs, changes to or removal of undocumented APIs, and changes to the documented or undocumented behavior of existing APIs for specific inputs.
9+
10+
## Browser Support
11+
12+
As of jQuery 4.0, the following browsers are supported:
13+
14+
* Internet Explorer: 11 only
15+
* Chrome, Edge, Firefox, Safari: Current and Current - 1
16+
* Opera: Current
17+
* Safari Mobile iOS: Current and Current - 1
18+
* Android: Current and Current - 1
19+
20+
Browser support will not change until the next major version of jQuery (5.0).
21+
22+
## jQuery Migrate Plugin
23+
24+
A new version of the [jQuery Migrate Plugin](https://github.com/jquery/jquery-migrate/#README) is available to simplify migration of older code to version 4.0. We strongly recommend that you use this plugin as an upgrading tool, it will give specific advice about most of the major changes that may affect your code.
25+
26+
[Version 4.0 of the jQuery Migrate Plugin](https://github.com/jquery/jquery-migrate/#README) *does not* warn about or restore behaviors that were removed in previous major version changes such as jQuery 1.0, 2.0, or 3.0. Use the following steps to upgrade from a version of jQuery older than 1.11.0 or 2.1.0 to this new version 4.0:
27+
28+
### Start here if currently using jQuery <1.9
29+
30+
1. Upgrade the version of jQuery on the page to the latest 1.x or 2.x version.
31+
1. Add the uncompressed [jQuery Migrate 1.x Plugin](https://github.com/jquery/jquery-migrate/tree/1.x-stable/#README) to the page.
32+
1. (Optional but recommended) Upgrade any plugins in use since later versions are usually the most compatible with recent versions of jQuery.
33+
1. Test the page and resolve any warnings that appear on the console, using the [JQMIGRATE 1.x warning documentation](https://github.com/jquery/jquery-migrate/tree/1.x-stable/warnings.md) as a guide.
34+
1. Remove the jQuery Migrate 1.x plugin and ensure that the updated jQuery code on the page continues to work properly with only the latest jQuery 1.x/2.x in use.
35+
36+
### Start here if currently using jQuery >=1.9
37+
38+
1. Upgrade the version of jQuery on the page to the latest 4.x version.
39+
1. Add the uncompressed [jQuery Migrate 3.6.0 plugin](https://github.com/jquery/jquery-migrate/#README) to the page. jQuery Migrate 4.x will also work with the caveat that it will only support the same browsers as jQuery 4.x, but it is not yet released.
40+
1. (Optional but recommended) Upgrade any plugins in use since later versions are usually the most compatible with recent versions of jQuery.
41+
1. Test the page and resolve any warnings that appear on the console, using the [JQMIGRATE 4.x warning documentation](https://github.com/jquery/jquery-migrate/blob/master/warnings.md) as a guide. Report any bugs in third-party plugins to the plugin authors.
42+
43+
**Note:** Once jQuery 4.x is released, the jQuery Migrate 3.x plugin will be in maintenance mode and will only receive updates for critical bugs. This guide will be updated to reflect that change.
44+
45+
**Running multiple version of jQuery Migrate simultaneously is not supported.**
46+
47+
The uncompressed development version of the Migrate plugin includes console log output to warn when specific deprecated and/or removed features are being used. This makes it valuable as a migration debugging tool for finding and remediating issues in existing jQuery code and plugins.
48+
49+
The compressed version of the Migrate plugin does not generate any warnings, although it does issue a solitary console message that it has been included on the page. Migrate can be used on production sites when jQuery 3.0 or higher is desired but older incompatible jQuery code or plugins must also be used. Ideally this is only used as a short-term solution, since restoring old behavior may cause conflicts with new jQuery code that expects the new behavior.
50+
51+
## Summary of Important Changes
52+
53+
With a library as widely used as jQuery, it is often difficult for the team to know which changes may impact developers the most before a release occurs. Despite the length of this list, we believe that the majority are edge cases. Many jQuery projects should be able to run version 4.0 with only minor changes, if any.
54+
55+
Changes are listed by their component category, and prefixed with a description to help you understand its impact:
56+
57+
* **Breaking change:** This change *may* affect existing code, since it changes the API surface in some way. Most of the time the impacts are only for specific edge cases as noted.
58+
* **Feature:** The change is an API addition and should not affect existing code in most cases. However, there is the possibility that new features can interact negatively with existing code.
59+
* **Deprecated:** This feature or API is still present in jQuery 3.0, but its use is discouraged. It may be removed in a future major-version update.
60+
61+
Remember that the jQuery Migrate plugin described above can detect and warn about many of these changes so that they can be fixed in your code.
62+
63+
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).
64+
65+
### Ajax
66+
67+
#### Breaking change: JSON to JSONP auto-promotion removed
68+
69+
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.
70+
71+
Auto-promoting JSON requests to JSONP introduced a security issue. The developer may be unaware they are executing code from a remote domain. The auto-promoting logic has been disabled.
72+
73+
To trigger a JSONP request, it's now required to specify `dataType: "jsonp"`.
74+
75+
#### Breaking change: Scripts are no longer auto-executed without `dataType: "script"`
76+
77+
jQuery 3.0.0 had already stopped auto-executing scripts retrieved with `jQuery.ajax` unless `dataType: "script"` was explicitly set for cross-domain scripts. That change has now been extended to same-domain scripts.
78+
79+
To fetch *and* evaluate a script, pass `dataType: "script"` in `jQuery.ajax` options or use `jQuery.getScript`.
80+
81+
#### Breaking change: Script tags now used for all async requests
82+
83+
Until jQuery 4.0, the AJAX script transport only used a script tag to load scripts for cross-domain requests or ones with `scriptAttrs` set. We now always use a script tag for async requests to avoid any [Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) errors.
84+
85+
This change may affect existing code if certain scripts were expected to execute even when CSP headers were set. Either modify the CSP header to allow scripts from the same domain or remove the scripts.
86+
87+
### Attributes
88+
89+
#### Breaking change: `toggleClass(boolean | undefined)` signature removed
90+
91+
This particular signature was deprecated in jQuery 3.0 and is now being removed in jQuery 4.0. After feedback and discussion with the community, it was determined that this signature caused unexpected behavior. For instance, if th C4DF e argument to `toggleClass` was a variable that turned out to be `undefined` or `false`, it would result in all classes being removed. Also, while the `toggleClass( boolean )` signature was documented (and has been marked deprecated since 3.0), the `toggleClass( undefined )` signature was not.
92+
93+
The recommendation for migration is to be explicit about which classes should be toggled.
94+
95+
### Core
96+
97+
#### Breaking change: Several deprecated APIs removed
98+
99+
The following APIs were deprecated in previous versions and have been removed in jQuery 4.0:
100+
101+
* `jQuery.camelCase`
102+
This function was never documented and was only used internally. It was deprecated in jQuery 3.0.
103+
104+
* `jQuery.cssProps`
105+
This object was used to map CSS properties to their vendor-prefixed versions, which is no longer necessary in jQuery 4.0's supported browsers.
106+
107+
* `jQuery.isArray`
108+
* `jQuery.isFunction`
109+
* `jQuery.isNumeric`
110+
* `jQuery.isWindow`
111+
* `jQuery.fx.interval`
112+
* `jQuery.parseJSON`
113+
* `jQuery.nodeName`
114+
* `jQuery.now`
115+
* `jQuery.trim`
116+
* `jQuery.type`

0 commit comments

Comments
 (0)
0