From 124eb7c046cf5611e5bc59b21334f6a50bf1cf1d Mon Sep 17 00:00:00 2001 From: Yavor Ivanov Date: Wed, 26 Jun 2024 09:32:27 +0200 Subject: [PATCH] [INTERNAL] UI5 Tooling v4 migration guide (#968) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit JIRA: CPOUI5FOUNDATION-847 Some of the required documentation would be handled with: https://github.com/SAP/ui5-tooling/pull/963 This migration guide tries to reflects changes described here: https://github.com/SAP/ui5-tooling/issues/701 --------- Co-authored-by: Florian Vogt Co-authored-by: Günter Klatt <57760635+KlattG@users.noreply.github.com> Co-authored-by: Merlin Beutlberger --- docs/updates/migrate-v4.md | 104 +++++++++++++++++++++++-------------- 1 file changed, 65 insertions(+), 39 deletions(-) diff --git a/docs/updates/migrate-v4.md b/docs/updates/migrate-v4.md index e8c936f591..9f2c82f4f8 100644 --- a/docs/updates/migrate-v4.md +++ b/docs/updates/migrate-v4.md @@ -9,59 +9,85 @@ ## Node.js and npm Version Support -To be defined +**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. ## Specification Versions Support -To be defined +Going forward, **only 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. ## Changes for Projects -To be defined +!!! info + ✅ Projects defining **Specification Version 2.x** are expected to be **fully compatible with UI5 Tooling v4** + +For projects defining the latest **Specification Versions 4.0 and higher**, some changes apply: + +* **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. + +* **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. + +See also [Configuration: Specification Version 4.0](../pages/Configuration.md#specification-version-40). + +## Migrate Your Code + + +### Changes to @ui5/cli + +Occurrences of `console.log` in the code base are replaced with `process.stderr`. +Аny scripts that capture the output from `console.log` need to be adjusted to rely on `process.stderr`. + +### Changes to @ui5/fs + +Non-public `DuplexCollection#byGlobSource` API has been removed. -### Migrate Your Code +### Changes to @ui5/builder -To be defined +- **Bundling**: The `usePredefineCalls` option has been removed. Bundling now enforces the use of `sap.ui.predefine` instead of function wrappers. -## Changes to @ui5/cli +- **Task API**: The `namespace` option has been renamed to `projectNamespace`. For more information, check the documentation for [CustomTasks API](../pages/extensibility/CustomTasks.md#task-implementation) -To be defined +- **New Option**: Added a new `async` option for `builder.bundles.bundleDefinition.section`. -## Update of Standard Tasks and Processors +!!! example + ```yaml + builder: + bundles: + - bundleDefinition: + name: "app.js" + sections: + - mode: require + filters: + - some/app/Component.js + resolve: true + sort: true + async: true + ``` -To be defined +### Changes to @ui5/project -**Updated list of standard tasks:** +- **Default Workspace Name**: The default `workspaceName` is now `"default"` for API usage. -| Task | Type `application` | Type `library` | Type `theme-library` | -| ------------------------------ | :----------------: | :------------: | :------------------: | -| escapeNonAsciiCharacters | *enabled* | *enabled* | | -| replaceCopyright | *enabled* | *enabled* | *enabled* | -| replaceVersion | *enabled* | *enabled* | *enabled* | -| replaceBuildtime | | *enabled* | | -| generateJsdoc | | *disabled* ^1^ | | -| executeJsdocSdkTransformation | | *disabled* ^1^ | | -| minify | *enabled* | *enabled* | | -| generateFlexChangesBundle | *enabled* | *enabled* | | -| generateLibraryManifest | | *enabled* | | -| generateComponentPreload | *enabled* | *disabled* ^2^ | | -| generateLibraryPreload | | *enabled* | | -| generateStandaloneAppBundle | *disabled* ^3^ | | | -| transformBootstrapHtml | *disabled* ^3^ | | | -| generateBundle | *disabled* ^4^ | *disabled* ^4^ | | -| buildThemes | | *enabled* | *enabled* | -| generateThemeDesignerResources | | *disabled* ^5^ | *disabled* ^5^ | -| generateVersionInfo | *disabled* | | | -| generateCachebusterInfo | *disabled* | | | -| generateApiIndex | *disabled* ^1^ | | | -| generateResourcesJson | *disabled* | *disabled* | *disabled* | +!!! example + ```js + import {graphFromPackageDependencies} from "@ui5/project/graph"; + + graphFromPackageDependencies({ + /* workspaceName: "default" */ + }); + ``` -*Disabled tasks can be activated by certain build modes, the project configuration, or by using the `--include-task` [CLI parameter](../pages/CLI.md#ui5-build). See footnotes where given* +- **Directory Naming**: The `ui5HomeDir` has been renamed to `ui5DataDir` in APIs. ---- +!!! example + ```js + import Resolver from "@ui5/project/ui5Framework/Openui5Resolver"; -^1^ Enabled in `jsdoc` build, which disables most of the other tasks -^2^ Enabled for projects defining a [component preload configuration](../pages/Configuration.md#component-preload-generation) -^3^ Enabled in `self-contained` build, which disables `generateComponentPreload` and `generateLibraryPreload` -^4^ Enabled for projects defining a [bundle configuration](../pages/Configuration.md#custom-bundling) -^5^ Can be enabled for framework projects via the `includeTask` option. For other projects, this task is skipped + await Resolver.resolveVersion("1.120.15", { + ui5DataDir: "~/.ui5", + cwd: process.cwd() + }); + ```