Skip to content

Commit c9413ee

Browse files
RandomByteRandomByte
committed
[INTERNAL] Add v3 migration guide from v2 branch
1 parent f6db35b commit c9413ee

File tree

1 file changed

+128
-0
lines changed

1 file changed

+128
-0
lines changed

‎docs/updates/migrate-v3.md‎

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
# Migrate to v3
2+
3+
!!! warning
4+
**UI5 Tooling v3 is currently in development.** Further breaking changes are expected.
5+
The latest development version can be installed via `npm i --save-dev @ui5/cli@next`
6+
7+
## Node.js and npm Version Support
8+
9+
**Only Node.js v16.13.2 and npm v8 or higher are supported.**
10+
Support for older Node.js and npm releases has been dropped.
11+
12+
## Specification Versions Support
13+
14+
Going forward, **only projects with Specification Versions 2.0 and higher are supported.**
15+
16+
In case a legacy specification version is detected, **an automatic migration is attempted.**
17+
This means your old projects might still work. Unless they have non-standard configuration in their ui5.yaml.
18+
19+
## Changes to @ui5/project and @ui5/builder APIs
20+
21+
The `normalizer` and `projectTree` APIs have been removed. The `builder` API has been moved from @ui5/builder to @ui5/project.
22+
23+
The JSON based, internal representation of a project dependency tree has been replaced with a graph. This resulted in a major refactoring of @ui5/project and made us change the APIs in an incompatible way.
24+
25+
!!! note
26+
The `ui5.dependencies` package.json configuration becomes obsolete and is ignored in UI5 Tooling v3.
27+
28+
`dependencies`, `devDependencies` and `optionalDependencies` are [automatically analyzed](https://github.com/SAP/ui5-project/blob/ff04ae4aeeb7f7d889dffd0c0e3e8774dd708c79/lib/graph/providers/NodePackageDependencies.js#L104).
29+
If a dependency can be configured as a UI5 project or UI5 Tooling extension, it is added to the graph and it's `dependencies` are analyzed.
30+
31+
Note that `devDependencies` and `optionalDependencies` are ignored for all but the current root project.
32+
33+
Note that also the @ui5/server API has been changed. Instead of a `tree`, it now only accepts a `graph` instance as the first parameter.
34+
35+
## JSDoc processor now fails when JSDoc reports an error
36+
37+
The `jsdocGenerator` processor and the corresponding `generateJsdoc` task will now throw an error when JSDoc reports an error (exit code != 0). This will also fail the build when running `ui5 build jsdoc`.
38+
39+
### Migrating Your Code
40+
41+
**@ui5/project v2**
42+
43+
````javascript
44+
const {normalizer} = require("@ui5/project");
45+
const {builder} = require("@ui5/builder");
46+
47+
const tree = await normalizer.generateProjectTree({cwd: "."});
48+
49+
await builder.build({
50+
tree,
51+
destPath: "./dist",
52+
buildDependencies: true,
53+
});
54+
````
55+
56+
**@ui5/project v3**
57+
58+
````javascript
59+
const {generateProjectGraph} = require("@ui5/project");
60+
61+
let graph = await generateProjectGraph.usingNodePackageDependencies({cwd: "."});
62+
63+
await graph.build({
64+
destPath: "./dist",
65+
includedDependencies: ["*"], // Parameter "buildDependencies" has been removed
66+
});
67+
````
68+
69+
## Removal of Standard Tasks and Processors
70+
71+
The following tasks have been removed:
72+
73+
- createDebugFiles
74+
- generateManifestBundle
75+
- uglify
76+
77+
The following processors have been removed:
78+
79+
- debugFileCreator
80+
- manifestBundler
81+
- resourceCopier
82+
- uglifier
83+
84+
**Task Migration**
85+
86+
| UI5 Tooling v2 | UI5 Tooling v3 | Note |
87+
| --------------------------- | --------------------------- | ------------------------- |
88+
| createDebugFiles<br/>uglify | minify | The minify task is executed earlier, before the bundling process takes place. Any existing 'beforeTask' or 'afterTask' configuration of custom tasks might need to be adapted to cater for this change. |
89+
| generateVersionInfo | generateVersionInfo | The task is no longer executed by default for application projects. It can be re-enabled by using the `--include-task` parameter. |
90+
| generateManifestBundle | *None* | This task was only needed for the HTML5 repository in Cloud Foundry. Meanwhile, the HTML5 repository implemented its own mechanism, so the task is no longer needed |
91+
92+
93+
**Updated list of standard tasks:**
94+
95+
| Task | Type `application` | Type `library` | Type `theme-library` |
96+
| ------------------------- | :----------------: | :------------: | :------------------: |
97+
| escapeNonAsciiCharacters | *enabled* | *enabled* | |
98+
| replaceCopyright | *enabled* | *enabled* | *enabled* |
99+
| replaceVersion | *enabled* | *enabled* | *enabled* |
100+
| replaceBuildtime | | *enabled* | |
101+
| generateJsdoc | | *disabled* ^1^ | |
102+
| executeJsdocSdkTransformation | | *disabled* ^1^ | |
103+
| **ADDED:** minify | *enabled* | *enabled* | |
104+
| generateFlexChangesBundle | | *enabled* | |
105+
| **REMOVED:** ~~generateManifestBundle~~ | *~~disabled~~* | *~~disabled~~* | |
106+
| generateLibraryManifest | | *enabled* | |
107+
| generateComponentPreload | *enabled* | *disabled* ^2^ | |
108+
| generateLibraryPreload | | *enabled* | |
109+
| generateStandaloneAppBundle | *disabled* ^3^ | | |
110+
| transformBootstrapHtml | *disabled* ^3^ | | |
111+
| generateBundle | *disabled* ^4^ | *disabled* ^4^ | |
112+
| buildThemes | | *enabled* | *enabled* |
113+
| generateThemeDesignerResources | | *disabled* | *disabled* |
114+
| **REMOVED:** ~~createDebugFiles~~ | *~~enabled~~* | *~~enabled~~* | |
115+
| **REMOVED:** ~~uglify~~ | *~~enabled~~* | *~~enabled~~* | |
116+
| generateVersionInfo | **disabled** | | |
117+
| generateCachebusterInfo | *disabled* | | |
118+
| generateApiIndex | *disabled* ^1^ | | |
119+
| generateResourcesJson | *disabled* | *disabled* | *disabled* |
120+
121+
*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*
122+
123+
---
124+
125+
^1^ Enabled in `jsdoc` build, which disables most of the other tasks
126+
^2^ Enabled for projects defining a [component preload configuration](../pages/Configuration.md#component-preload-generation)
127+
^3^ Enabled in `self-contained` build, which disables `generateComponentPreload` and `generateLibraryPreload`
128+
^4^ Enabled for projects defining a [bundle configuration](../pages/Configuration.md#custom-bundling)

0 commit comments

Comments
 (0)