SAP Spartacus 升級時關於 schematics 的更新

When upgrading Spartacus to a new major version (for example, from 3.x to 4.0), the Spartacus migration mechanism automatically implements fixes for code that is modified or removed in the new version.

當升級 Spartacus 到新的 major 版本時，Spartacus migration mechaniusm 自動調整在新版本里被修改或者被刪除的代碼。

When you are working on a feature or a bug, or making any other change to the Spartacus source code, you need to update the schematics as part of the Definition Of Done..

Migration Mechanism

After upgrading to a new major version, the migration mechanism should be updated at the very beginning of the new development cycle.

在升級到新的 major 版本後，migration mechanism 應在新的開發流程初始階段，儘快被更新。

For example, if Spartacus has been updated from version 2.x to 3.0, the updated mechanism should be merged to the develop branch as soon as possible.

例如，Spartacus 從 2.X 升級到 3.0 時，更新後的 mechanism 應該儘快被 merge 到 develop 分支。

This allows contributors to include migrations with their features and bug fixes from the very start of the development cycle.

這能確保社區貢獻者們在開始新的開發流程以前，把 migration 和本身的功能開發以及 bug 修復所有包含進來。

The projects/schematics/src/migrations/migrations.json file contains a list of all the migration scripts for every Spartacus version.

migrations.json 文件包含了每一個 Spartacus 版本的 migration scripts.

一個例子：

每一個 migration script 都有一系列屬性。

name

格式以下：migration-v<version>-<migration-feature-name>-<sequence-number>.

• version: migration 的目標版本。
• migration-feature-name: 描述 Migration 的具體內容。
• sequence-number：腳本執行順序。

其中 version 屬性相當重要：version is very important for the Angular update mechanism. It is used to automatically run the required migration scripts for a specific version.

用來自動運行所需的 Migration 腳本。

• factory: 指向真正的 Migration 腳本。

Constructor Deprecation

The projects/schematics/src/migrations/2_0/constructor-deprecations.ts performs the constructor migration tasks.

constructor-deprecations.ts 這個文件執行構造函數遷移任務。

Usually, a developer does not need to touch this file, and instead should describe constructor deprecations in projects/schematics/src/migrations/2_0/constructor-deprecation-data.ts.

開發人員不須要直接修改該文件，而是維護這個文件：projects/schematics/src/migrations/2_0/constructor-deprecation-data.ts.

• The CONSTRUCTOR_DEPRECATION_DATA constant describes the deprecated constructor, and includes the addParams and removeParams properties that allow you to specify which parameters should be added or removed, respectively.

CONSTRUCTOR_DEPRECATION_DATA 這個常量，描述了 deprecated 構造函數，包含 addParams 和 removeParams，能指定哪些構造函數參數被添加或者刪除。

Commenting Code

When it is not possible to automatically migrate code, we often place a comment in the customer’s code base that describes what the customer should do to upgrade their project to the new version of Spartacus.

當不可能自動 migrate 代碼時，咱們能夠在客戶基準代碼里加上一些註釋，告訴客戶如何手動升級其項目到最新的 Spartacus 版本。

We should do this only in cases where upgrading manually is easy, and writing a migration script would be too complex.

請謹慎使用該方法，最佳的適用場合是，手動升級很容易，而且須要極大的工做量才能完成 Migration 腳本編寫時。

The projects/schematics/src/shared/utils/file-utils.ts#insertCommentAboveIdentifier method adds comments above the specified identifier TypeScript node.

The following are examples of how you might add a comment:

• If you removed an API method, you could add a comment above the removed method that suggests which method can be used instead.
• If you changed the parameters of an NgRx action, you could add a comment above the action where the parameters were changed.

Component Deprecation

Similar to constructor deprecation, projects/schematics/src/migrations/2_0/component-deprecations.ts performs component migration tasks, for both component *.ts and HTML templates.

Usually, a developer does not need to touch this file, and instead should describe component deprecations in projects/schematics/src/migrations/2_0/component-deprecations-data.ts. The COMPONENT_DEPRECATION_DATA constant describes the deprecated components.

原理和構造函數 deprecation 相似。

添加 migration 的流程

1. Check whether any of the changed files are exported in the public API. If no, then no further action is required.

檢查被修改的文件是否被導出爲 public API，若是否，什麼都不用作。

1. Check whether any of the changes you have made are breaking changes. If not, no further action is required.

若是作的修改不包含 breaking changes，什麼都不用作。

1. 若是是 breaking change，須要將修改記錄到對應的 Migration 文件裏，好比：docs/migration/3_0.md.
2. Build automation tasks, as described in the Validations, Constructor Deprecation, and Component Deprecation) sections, above.

構建自動化任務。

1. Test the added migrations by running tests, trying to migrate an example app, and so on.

能夠經過運行測試的方式，測試新建的 Migration.

能夠參考這個 pull request：https://github.com/SAP/sparta...

更多Jerry的原創文章，盡在："汪子熙":