[ACS-9880] Create ADF upgrade guide from 7.0.0 to 8.0.0 (#11029)

* [ACS-9880] add ADF upgrade from 7.0.0 to 8.0.0 guide * [ACS-9880] add missing commas and values [ci:force]
2025-07-24 17:32:15 +00:00 · 2025-07-18 14:19:06 +02:00
parent b28479b92b
commit f15014f295
1 changed files with 164 additions and 0 deletions
--- a/docs/upgrade-guide/upgrade-7.0.0-8.0.0.md
+++ b/docs/upgrade-guide/upgrade-7.0.0-8.0.0.md
@@ -0,0 +1,164 @@
+---
+Title: Upgrading from ADF v7.0 to v8.0
+---
+
+# Upgrading from ADF v7.0 to v8.0
+
+This guide provides instructions for upgrading your v7.0.0 ADF projects to v8.0.0.
+
+## Before you begin
+
+Always perform upgrades on a "clean" project state. Back up your changes or create a full project backup before proceeding.
+
+```shell
+# Recommended clean up
+nx reset && rm -rf .angular .nx dist node_modules nxcache tmp
+```
+
+## Libraries
+
+Update your dependencies to the versions introduced in the 8.0.0 release:
+
+```json
+{
+    "dependencies": {
+        "@alfresco/adf-core": "8.0.0",
+        "@alfresco/adf-content-services": "8.0.0",
+        "@alfresco/adf-process-services-cloud": "8.0.0",
+        "@alfresco/adf-insights": "8.0.0",
+        "@alfresco/adf-extensions": "8.0.0",
+        "@alfresco/adf-cli": "8.0.0",
+        "@alfresco/eslint-plugin-eslint-angular": "8.0.0",
+        "@alfresco/adf-testing": "8.0.0",
+        "@alfresco/js-api": "9.0.0"
+    }
+}
+```
+
+Currently used Node version: 22.14.0.
+
+### Breaking changes
+
+Major version updates have been applied to the following core libraries:
+
+- Angular: 19.2.6
+- Angular Material: 19.2.9
+- Typescript: 5.8.2
+
+> Details on Angular update can be found in *Update Guide* from Angular documentation.
+
+### Added libraries
+
+```json
+{
+    "dependencies": {
+        "node-fetch": "^3.3.2"
+    },
+    "devDependencies": {
+        "resize-observer-polyfill": "^1.5.1",
+        "webdriver-manager": "12.1.9"
+    }
+}
+```
+
+### Deleted libraries
+
+```json
+{
+    "devDependencies": {
+        "mini-css-extract-plugin": "X.X.X",
+        "css-loader": "X.X.X"
+    }
+}
+```
+
+Reinstall your dependencies and perform an initial build:
+
+```shell
+npm i
+npm run build
+```
+
+Review your applications as some styles and classes of Angular Material components might have changed.
+
+## Deprecations
+
+The following table lists deprecated features and modules that will be removed in upcoming releases. Consider replacing them as soon as you update ADF to minimize future technical debt.
+
+| Name                          | Notes                                                                                         |
+|-------------------------------|-----------------------------------------------------------------------------------------------|
+| Custom Theme                  | Refer to [Custom Theme documentation](../../lib/core/custom-theme/README.md)                  |
+| ShellModule                   | Refer to [Shell documentation](../../lib/core/shell/README.md)                                |
+| FormBaseModule                | Use standalone components instead.                                                            |
+| CoreTestingModule             | Use standalone components instead.                                                            |
+| ProcessServicesCloudModule    | Refer to [ProcessServicesCloudModule replacement](#processservicescloudmodule-replacement)    |
+
+### ProcessServicesCloudModule replacement
+
+To replace this module, import the standalone components directly or use the following provider API to replicate its behavior:
+
+```typescript
+providers: [
+    provideTranslations('adf-process-services-cloud', 'assets/adf-process-services-cloud'),
+    provideCloudPreferences(),
+    provideCloudFormRenderer(),
+    { provide: TASK_LIST_CLOUD_TOKEN, useClass: TaskListCloudService }
+]
+```
+
+## New features and APIs
+
+You can start using the new features and APIs introduced in the 8.0.0 release.
+
+### XMLHttpRequest.withCredentials
+
+Support for disabling the `withCredentials` property in `app.config.json` for identity providers that disallow credentials has been introduced. You can configure it as shown below:
+
+```json
+{
+    "auth": {
+        "withCredentials": false
+    }
+}
+```
+
+### provideShell
+
+The new provideShell API for providing the main application layout can replace the `withRoutes(routes: Routes | AppShellRoutesConfig)` method, as shown below.
+
+```typescript
+import { provideShell } from '@alfresco/adf-core/shell';
+
+provideShell(
+    {
+        routes: [],
+        appService: AppService,
+        authGuard: AuthGuard,
+        navBar: {
+            minWidth: 0,
+            maxWidth: 100
+        }
+    }
+)
+```
+
+### provideI18N
+
+The new `provideI18N` API for providing translation can replace `provideTranslations('app', 'assets')` method, as shown below.
+
+```typescript
+import { provideI18N } from '@alfresco/adf-core';
+
+provideI18N(
+    {
+        defaultLanguage: "en", // optional, defaults to "en"
+        assets: [['en', '/assets/i18n/en.json'], ['fr', '/assets/i18n/fr.json']] 
+    }
+)
+```
+
+## Final steps
+
+After updating your code, thoroughly test your application to ensure everything works as expected.
+
+If you encounter any issues during the upgrade process, refer to the Angular update guide or seek assistance from the ADF community.