Upgrade: update jQuery 4.0 upgrade guide now that 4.0 is released

pages/upgrade-guide/4.0.md

@@ -3,9 +3,6 @@
 	"toc": true
 }</script>
 
-> [!NOTE]
-> jQuery 4.0 is not yet released. This is a draft of the jQuery 4.0 upgrade guide. jQuery 4.0 is currently in development and this guide will be updated as changes are finalized. The jQuery team welcomes feedback on this guide and the changes in jQuery 4.0.
-
 ## Overview
 
 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. 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.
@@ -35,22 +32,32 @@ A new version of the [jQuery Migrate Plugin](https://github.com/jquery/jquery-mi
 
 [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:
 
-### Start here if currently using jQuery <1.9
+### Start here if currently using jQuery 1.x or 2.x
 
 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.
+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 1.x warning documentation](https://github.com/jquery/jquery-migrate/tree/1.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 1.x/2.x in use.
+
+### Start here if currently using the latest jQuery 1.x or 2.x version
+
+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.
 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 1.x  warning documentation](https://github.com/jquery/jquery-migrate/tree/1.x-stable/warnings.md) as a guide.
-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.
+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.
 
-### Start here if currently using jQuery >=1.9
+### Start here if currently using jQuery 3.x
 
 1. Upgrade the version of jQuery on the page to the latest 4.x version.
-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.
+1. Add the uncompressed [jQuery Migrate 4.x plugin](https://github.com/jquery/jquery-migrate/) 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 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.
+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 4.x in use.
 
-**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 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.
 
 **Running multiple version of jQuery Migrate simultaneously is not supported.**
 
@@ -66,11 +73,13 @@ Changes are listed by their component category, and prefixed with a description
 
 * **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.
 * **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.
-* **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.
+* **Deprecated:** This feature or API is still present in jQuery 4.0, but its use is discouraged. It may be removed in a future major-version update.
 
 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).
+
+jQuery 4.0.0 is compatible with jQuery UI 1.13.3 or newer.
 
 ### Ajax
 
@@ -167,6 +176,24 @@ The slim build of jQuery 4.0 no longer includes the `callbacks`, `deferred`, and
 
 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 should not affect existing code in most cases, but it is an important fix to ensure that jQuery can be used in a wider range of environments.
 
+##### Potentially breaking change: Node.js without a DOM window requires the factory entry point
+
+Wherever jQuery is used, it requires a `window` with a proper `document`, which does not exist by default in Node.js and related environments. Tools like JSDOM can be used to create a fake `window` and `document` in Node.js, but the way jQuery can be imported in these environments has changed in jQuery 4.0.
+
+In jQuery 3.x, `require("jquery")` in a Node.js environment without a global `window` returned a factory function that accepted a `window` argument. In jQuery 4.0, the CommonJS wrapper no longer does this. Instead, use the dedicated factory entry point:
+
+```js
+// jQuery 3.x
+const jQuery = require( "jquery" )( window );
+
+// jQuery 4.0
+const jQuery = require( "jquery/factory" )( window );
+```
+
+A `jquery/factory-slim` entry point is also available.
+
+Alternatively, if you attach the JSDOM `window` to `globalThis` before importing or requiring jQuery, it will work without the factory entry point.
+
 #### Potentially breaking change: jQuery's source is no longer written using AMD modules
 
 jQuery's source code has been converted to use ES modules instead of AMD modules. While this has several advantages, some users may have been importing jQuery's source directly using AMD loaders such as RequireJS. This change may affect those users, but it is expected that most users will be able to continue using jQuery without any issues. The main jQuery file is still built as a UMD module, so it can be used in both AMD and non-AMD environments.
@@ -175,10 +202,12 @@ jQuery's source code has been converted to use ES modules instead of AMD modules
 
 #### Breaking change: `px` no longer automatically added to most unitless values
 
-jQuery 4.0 switches strategies when it comes to setting CSS properties that require units. Previously, jQuery would automatically add `px` to unitless values, with some exceptions. This behavior has been removed in jQuery 4.0.
+jQuery 4.0 switches strategies when it comes to setting CSS properties that require units. Previously, jQuery would automatically add `px` to unitless values, with some exceptions. The old stragey did not properly handle new CSS properties that had been added to the CSS spec since jQuery's release and the "exceptions" list was growing fast. That behavior has been removed in jQuery 4.0.
 
 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.
 
+We encourage all users to explicitly specify units for CSS properties that require them, as this is the standard way of working with CSS and will help avoid any issues with future versions of jQuery. If the old behavior is still needed, see [the docs](https://api.jquery.com/css/#css-propertyName-value) for the current list of properties to which jQuery will automatically add `px`.
+
 #### Breaking change: Remove opacity CSS hook
 
 `.css( "opacity" )` will now return an empty string for detached elements in standard-compliant browsers and "1" in IE. That behavior is shared by most other CSS properties, but may affect existing code relying on a return value of "1".