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 的原创文章，尽在：” 汪子熙 ”: