[INTERNAL] Migrate v4: Update migration guide (#981)

Co-authored-by: Florian Vogt <[email protected]>
Co-authored-by: Günter Klatt <[email protected]>

docs/index.md

@@ -4,12 +4,12 @@
 
 An open and modular toolchain to develop state-of-the-art applications based on the [UI5](https://ui5.sap.com) framework.
 
-!!! tip "In Development"
-	**UI5 Tooling V4 is still in development 🚧**
+!!! tip "New Release"
+	**UI5 Tooling V4 is here 🎉**
 
-	Please use UI5 Tooling V3 by installing the latest version via: `npm i --save-dev @ui5/cli@latest`
+	Read the announcement blog post: **[SAP Community: UI5 Tooling 4.0](https://community.sap.com/t5/technology-blogs-by-sap/ui5-tooling-4-0/ba-p/13769578)**
 
-	And find the announcement blog post here: **[SAP Community: UI5 Tooling 3.0](https://blogs.sap.com/2023/02/10/ui5-tooling-3.0/)**
+    And checkout the **[Migrate to v4](./updates/migrate-v4.md)** documentation.
 
 [**Get Started**](./pages/GettingStarted.md){: .md-button .md-button--primary .sap-icon-initiative }
 

docs/pages/Builder.md

@@ -154,22 +154,29 @@ JavaScript port of the "legacy" Maven/Java based bundle tooling.
 ### JavaScript Files Requiring Top Level Scope
 UI5 Tooling packages JavaScript files that require "top level scope" as a string, provided your project uses a Specification Version lower than `4.0`. In this case, the code is evaluated using [`eval`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/eval) at runtime.
 
-This ensures that the script works as expected, e.g. with regards to implicitly used globals. However, this `eval` runtime feature will be discontinued with UI5 2.x because of security best practices (https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/eval) and to comply with stricter CSP settings (`unsafe-eval`). If your project defines [Specification Version 4.0](./Configuration.md#specification-version-40) or higher, files requiring top level scope are no longer part of the created bundle and following error is logged by UI5 Tooling `Module myFancyModule requires top level scope and can only be embedded as a string (requires 'eval'), which is not supported with specVersion 4.0 and higher. For more information, see the UI5 Tooling documentation https://sap.github.io/ui5-tooling/stable/pages/Builder/#javascript-files-requiring-top-level-scope`. Therefore, please adjust your code with one of the following options:
+This ensures that the script works as expected, e.g. with regards to implicitly used globals. However, this `eval` runtime feature will be discontinued with UI5 2.x because of [security best practices](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/eval) and to comply with stricter CSP settings (i.e. [unsafe-eval](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/script-src#unsafe_eval_expressions)).
+
+If your project defines [Specification Version 4.0](./Configuration.md#specification-version-40) or higher, files requiring top level scope are no longer part of the created bundle and following error is logged by UI5 Tooling:
+>  Module myFancyModule requires top level scope and can only be embedded as a string (requires 'eval'), which is not supported with specVersion 4.0 and higher.
+
+If you see this error message, please adjust your code by applying one of the following options:
 
 **Option 1**: Use [ui5-tooling-modules](https://www.npmjs.com/package/ui5-tooling-modules) to bundle third-party `npm` packages. It converts files to `sap.ui.define` modules automatically.
 
-**Option 2**: Wrap the respective files manually in `sap.ui.define` modules.
+**Option 2**: Wrap the respective files manually in `sap.ui.define` modules as shown below:
 
-*Before*:
-```js
-const myFancyModule = {};
-```
 
-*After*:
-```js
-sap.ui.define([], () => {
-    "use strict";
+!!! example
+    **Before**:
+    ```js
     const myFancyModule = {};
-    return myFancyModule;
-});
-```
+    ```
+
+    **After**:
+    ```js
+    sap.ui.define([], () => {
+        "use strict";
+        const myFancyModule = {};
+        return myFancyModule;
+    });
+    ```

docs/pages/Configuration.md

@@ -702,7 +702,9 @@ A list of bundle definitions. A `bundleDefinition` contains of the following opt
     - `declareRawModules`: Whether raw modules should be declared after jQuery.sap.global became available. With the usage of the ui5loader, this flag should be set to 'false'. By default set to `false`
     - `renderer`: Whether renderers for controls should be added to the module set. By default set to `false`
     - `sort`:  By default, modules are sorted by their dependencies. The sorting can be suppressed by setting the option to `false`
-    - `async`: Specifies whether the `require` section of the module should be asynchronous. When set to `true`, the modules will be loaded using `sap.ui.require` instead of `sap.ui.requireSync`. The latter API is not available in UI5 version 2.x. **Note:** This property is available only for `mode=require` and defaults to `true`
+    - `async` (only available if `mode` equals `require`): Specifies whether the `require` section of the module should use an asynchronous API. When set to `true`, the modules are loaded using `sap.ui.require`. When set to `false`, modules are loaded using `sap.ui.requireSync`, which is not available in UI5 2.x.
+        - Projects defining [Specification Version](#specification-versions) 4.0 and higher: Defaults to `true`
+        - Projects defining [Specification Version](#specification-versions) lower than 4.0: Behaves like `false` but can't be configured
 
 **bundleOptions**
 
@@ -756,11 +758,13 @@ Version | UI5 CLI Release
 
 **Breaking changes:**
 
-- Remove bundle option [`usePredefineCalls`](#properties). UI5 CLI v4.0.0 and above will always use predefine calls in bundles, making this option obsolete.
-- New option “async“ for [builder.bundles.bundleDefinition.section](#properties)
+- Removed bundle option [`usePredefineCalls`](#properties). UI5 CLI v4.0.0 and above will always use predefine calls in bundles, making this option obsolete.
+- Adds new a new option `async` for `bundleDefinition`-section configuration, see [Configuration: `bundleDefinition.sections`](../pages/Configuration.md#properties) for details.
 
 Specification Version 4.0 projects are supported by [UI5 CLI](https://github.com/SAP/ui5-cli) v4.0.0 and above.
 
+Also see [Migrate to v4](../updates/migrate-v4.md#changes-for-projects) for details on these breaking changes.
+
 ### Specification Version 3.2
 
 **Features:**

docs/pages/GettingStarted.md

@@ -1,7 +1,7 @@
 # Getting Started
 ## Installing the UI5 CLI
 ### Requirements
-- [Node.js](https://nodejs.org/) Versions 16.18.0, 18.12.0, or later
+- [Node.js](https://nodejs.org/) Versions v20.11.0, v22.0.0, or higher
 
 ### Installation
 ```sh

docs/updates/migrate-v3.md

@@ -1,11 +1,9 @@
 # Migrate to v3
 
-!!! tip "Now Released"
-	**UI5 Tooling 3.0 has been released February 9, 2023 🎉**
+!!! warning "Superseded"
+	**UI5 Tooling 3.0 has been superseded by version 4.0. See [Migrate to v4](./migrate-v4.md).**
 
-	Install the latest version via: `npm i --save-dev @ui5/cli@latest`
-
-	And find the announcement blog post here: **[SAP Community: UI5 Tooling 3.0](https://blogs.sap.com/2023/02/10/ui5-tooling-3.0/)**
+	Find the announcement blog post for version 3.0 here: **[SAP Community: UI5 Tooling 3.0](https://blogs.sap.com/2023/02/10/ui5-tooling-3.0/)**
 
 ## Node.js and npm Version Support
 

docs/updates/migrate-v4.md

@@ -1,39 +1,65 @@
 # Migrate to v4
 
 !!! tip "In Development"
-	**UI5 Tooling V4 is still in development 🚧**
+    **UI5 Tooling 4.0 has been released on July 24, 2024 🎉**
 
-	Please use UI5 Tooling V3 by installing the latest version via: `npm i --save-dev @ui5/cli@latest`
+    Install the latest version in your projects via: `npm i --save-dev @ui5/cli@latest`  
+    And update your global install via `npm i --global @ui5/cli@latest`
 
-	And find the announcement blog post here: **[SAP Community: UI5 Tooling 3.0](https://blogs.sap.com/2023/02/10/ui5-tooling-3.0/)**
+    And find the announcement blog post here: **[SAP Community: UI5 Tooling 4.0](https://community.sap.com/t5/technology-blogs-by-sap/ui5-tooling-4-0/ba-p/13769578)**
+
+## UI5 2.x Compatibility
+
+*Also see the blog post [SAP Community: Introducing OpenUI5 2.x](https://community.sap.com/t5/open-source-blogs/introducing-openui5-2-x/ba-p/13580633)*
+
+UI5 Tooling 4.0 is required for building UI5 2.x projects. The UI5 2.x framework libraries define Specification Version 4.0 and therefore can't be built using older UI5 Tooling versions.
+
+For applications and libraries running with UI5 2.x, the use of Specification Version 4.0 is not enforced. It is highly recommended, however, since only then UI5 Tooling will ensure UI5 2.x compatibility of the generated bundles.
 
 ## Node.js and npm Version Support
 
-**This release requires Node.js versions v20.11.0, v21.2.0 or higher as well as npm v10 or higher.**
-Support for older Node.js and npm releases has been dropped and will cause an error.
+This release requires **Node.js versions v20.11.0, v22.0.0, or higher** as well as npm v8 or higher.
+Support for older Node.js releases has been dropped; their use will cause an error.
 
 ## Specification Versions Support
 
-Going forward, **only projects with Specification Versions 2.0 and higher are supported.**
+As with UI5 Tooling 3.x, all projects with Specification Versions 2.0 and higher are supported.
 
-If a legacy specification version is detected, **an automatic migration is attempted.**
-Your old projects might therefore still work unless they have a non-standard configuration in their ui5.yaml.
+If a legacy specification version is detected, an automatic migration is attempted.
+Old projects might therefore still work, unless they have a non-standard configuration in their ui5.yaml.
 
 ## Changes for Projects
 
-!!! info
-    ✅ Projects defining **Specification Version 2.x** are expected to be **fully compatible with UI5 Tooling v4**
+!!! success "No changes for Specification Versions 2.x and 3.x"
+    Projects defining **Specification Version 2.x or 3.x** are expected to be **fully compatible with UI5 Tooling v4**
+
+    The following does not apply to them.
+
+For projects defining the latest **Specification Version 4.0 or higher**, the following changes apply:
+
+* **Breaking Change:** Bundling of JavaScript modules requiring "top level scope" as a string is terminated. 
+
+    In UI5 2.x, the feature of evaluating modules from a string is expected to be removed. Therefore, when using the latest Specification Version, UI5 Tooling will **omit affected module from the bundle and log an error message instead.**
+
+    For more details, see [Builder: JavaScript Files Requiring Top Level Scope](../pages/Builder.md#javascript-files-requiring-top-level-scope).
+
+* **Breaking Change:** New `async` option for the `require` sections of bundle definitions.
+
+    This option defaults to `true` for Specification Version 4.0 and higher, **which can influence the loading behavior of your project**. Require sections are now expressed using `sap.ui.require` instead of `sap.ui.requireSync`. The latter is not available in UI5 2.x.
 
-For projects defining the latest **Specification Versions 4.0 and higher**, some changes apply:
+    Note that the same default applies for all standard bundles as well, like the component- or library preloads as well as self-contained bundles.
 
-* **Breaking Change:** Remove the bundle option `usePredefineCalls`. UI5 CLI v4.0.0 and above will always use `sap.ui.predefine` calls in bundles, making this option obsolete. See [Configuration](../pages/Configuration.md#properties) for details.
+    See [Configuration: `bundleDefinition.sections`](../pages/Configuration.md#properties) for more on the new `async` option.
 
-* **Breaking Change:** New `async` option for `builder.bundles.bundleDefinition.section` with default value = `true`; only applicable if mode = "require". See [Configuration: `bundleDefinition.section`](../pages/Configuration.md#properties) for details.
+* **Breaking Change:** Removal of the `usePredefineCalls` [bundle option](../pages/Configuration.md#properties). UI5 Tooling v4 will _always_ use `sap.ui.predefine` calls in bundles, making this option obsolete.
+
+    **We do not expect any negative impact** on projects due to this change, therefore it is active independently of the Specification Version. However, when upgrading to Specification Version 4.0 you might need to remove the property if you have it in your ui5.yaml configuration.
 
-See also [Configuration: Specification Version 4.0](../pages/Configuration.md#specification-version-40).
+You can find a summary of the above at [Configuration: Specification Version 4.0](../pages/Configuration.md#specification-version-40).
 
-## Migrate Your Code 
+## Migrate Your Code
 
+When using the Node.js API of UI5 Tooling, or when integrating it into other tools, the following changes might be relevant to you:
 
 ### Changes to @ui5/cli
 

package.json

@@ -19,7 +19,7 @@
 	],
 	"type": "module",
 	"engines": {
-		"node": "^20.11.0 || >=22.4.1",
+		"node": "^20.11.0 || >=22.0.0",
 		"npm": ">= 8"
 	},
 	"scripts": {