SAP Spartacus 升级时关于 schematics 的更新

Posted 2021-10-22 JerryWang汪子熙

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 的目标版本。
• 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 的流程

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

检查被修改的文件是否被导出为 public API，如果否，什么都不用做。

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

如果做的修改不包含 breaking changes，什么都不用做。

4. 如果是 breaking change，需要将修改记录到对应的 Migration 文件里，比如：docs/migration/3_0.md.
5. Build automation tasks, as described in the Validations, Constructor Deprecation, and Component Deprecation) sections, above.

构建自动化任务。

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

可以通过运行测试的方式，测试新建的 Migration.

​

更多Jerry的原创文章，尽在："汪子熙":