Upgrade: update jQuery 4.0 upgrade guide now that 4.0 is released#259
Upgrade: update jQuery 4.0 upgrade guide now that 4.0 is released#259timmywil wants to merge 1 commit intojquery:mainfrom
Conversation
timmywil
force-pushed
the
chore/upgrade-guide-4.0
branch
from
74e2ae1 to
1ac86c8
Compare
timmywil
added
Needs review
Discuss in Meeting
mgol
left a comment
mgol
left a comment
There was a problem hiding this comment.
See comments; not a lot of changes needed.
|
|
||
| 1. Upgrade the version of jQuery on the page to the latest 1.x or 2.x version. | ||
| 1. Add the uncompressed [jQuery Migrate 1.x Plugin](https://github.com/jquery/jquery-migrate/tree/1.x-stable/#README) to the page. | ||
| 1. Add the uncompressed [jQuery Migrate 1.x Plugin](https://github.com/jquery/jquery-migrate/tree/1.x-stable/) to the page. |
There was a problem hiding this comment.
That's a nit, but GitHub doesn't use trailing slashes in canonical links, so let's drop them here as well:
| 1. Add the uncompressed [jQuery Migrate 1.x Plugin](https://github.com/jquery/jquery-migrate/tree/1.x-stable/) to the page. | |
| 1. Add the uncompressed [jQuery Migrate 1.x Plugin](https://github.com/jquery/jquery-migrate/tree/1.x-stable) to the page. |
|
|
||
| ### Start here if currently using jQuery >=1.9 | ||
| 1. Upgrade the version of jQuery on the page to the latest 3.x version. | ||
| 1. Add the uncompressed [jQuery Migrate 3.x Plugin](https://github.com/jquery/jquery-migrate/tree/3.x-stable/) to the page. |
There was a problem hiding this comment.
| 1. Add the uncompressed [jQuery Migrate 3.x Plugin](https://github.com/jquery/jquery-migrate/tree/3.x-stable/) to the page. | |
| 1. Add the uncompressed [jQuery Migrate 3.x Plugin](https://github.com/jquery/jquery-migrate/tree/3.x-stable) to the page. |
| 1. Add the uncompressed [jQuery Migrate 3.x Plugin](https://github.com/jquery/jquery-migrate/tree/3.x-stable/) to the page. | ||
| 1. (Optional but recommended) Upgrade any plugins in use since later versions are usually the most compatible with recent versions of jQuery. | ||
| 1. Test the page and resolve any warnings that appear on the console, using the [JQMIGRATE 3.x warning documentation](https://github.com/jquery/jquery-migrate/tree/3.x-stable/warnings.md) as a guide. | ||
| 1. Remove the jQuery Migrate plugin and ensure that the updated jQuery code on the page continues to work properly with only the latest jQuery 3.x in use. |
There was a problem hiding this comment.
There's a case where someone is already on the latest 3.x. The current steps require them to add Migrate, resolve warnings & remove Migrate, ensuring the app still works.
I wonder if we can simplify it. Technically speaking, you should be able to update straight from any 3.x version to the latest 4.x + the latest Migrate 4.x, skipping a step. Adding Migrate 3.x to an existing Core 3.x project has mostly value in preparing for a future 4.x update if you cannot do it yet (e.g. because a third party plugin is not compatible yet).
Let's think about it, but not in this PR. This PR is strictly a big improvement over what we have right now and I'd rather not delay it.
|
|
||
| **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. | ||
| > [!Note] | ||
| > jQuery Migrate 1.x, 2.x, and 3.x are in maintenance mode and will only receive updates for critical bugs. jQuery Migrate 3.x can be used to migrate to the latest jQuery 3.x if support for older browsers is needed. |
| 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. | ||
|
|
||
| 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). | ||
| For a complete and detailed list of all code changes, see the 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). |
There was a problem hiding this comment.
That's not the diff between 3.7.1 & 4.0.0 but between the base commit of 3.7.1 & 4.0.0, and 4.0.0. The branch was forked before 3.4.0, so this is actually a list of changes between 3.3.1/3.4.0 & 4.0.0.
A true diff is https://github.com/jquery/jquery/compare/3.7.1..4.0.0, but without a list of commits, so probably not very useful.
Maybe only display a milestone. Although lots of stuff that landed in 4.0.0 also landed in 3.x-stable and will only arrive in 3.8.0. But we plan to release 3.8.0 soon, so this may be OK.
There was a problem hiding this comment.
Let's also add a note about jQuery UI compatibility, something like:
jQuery 4.0 is compatible with jQuery UI 1.13.3 or older
I'll submit a PR adding relevant test to the 1.13 branch. I don't plan any new UI 1.13 releases, this is just so that I have a confirmation that it works.
2 participants
Fixes gh-258