Skip to content

Commit

Permalink
[INTERNAL] UI5 Tooling v4 migration guide (#968)
Browse files Browse the repository at this point in the history 
JIRA: CPOUI5FOUNDATION-847

Some of the required documentation would be handled with:
#963

This migration guide tries to reflects changes described here:
#701

---------

Co-authored-by: Florian Vogt <florian.vogt@sap.com>
Co-authored-by: Günter Klatt <57760635+KlattG@users.noreply.github.com>
Co-authored-by: Merlin Beutlberger <m.beutlberger@sap.com>
  • Loading branch information
@d3xter666 @flovogt
@KlattG @RandomByte
4 people committed Jun 26, 2024
1 parent d75e0f0 commit 124eb7c
Showing 1 changed file with 65 additions and 39 deletions.
104 changes: 65 additions & 39 deletions docs/updates/migrate-v4.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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()
});
```

0 comments on commit 124eb7c

Please sign in to comment.