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 的流程

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

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

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

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

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

构建自动化任务。

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

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

可以参考这个 pull request：https://github.com/SAP/spartacus/pull/9946/files

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

SAP Spartacus 升级时关于 schematics 的更新相关推荐

SAP Spartacus 找不到登录入口的问题 - 如何使用 Schematics 安装 user package
如下图所示:本地打开 SAP Spartacus 页面,右上角找不到登录链接: 查看 package.json,发现因为我没有安装 @spartacus/user 这个 package: @spart ...
使用Schematics启用SAP Spartacus的SSR模式
命令行: ng add @spartacus/schematics --ssr src文件夹下,自动创建main.server.ts, server.ts文件: 命令行: npm run build: ...
什么是SAP Spartacus schematics
https://sap.github.io/spartacus-docs/schematics/ SAP Spartacus Schematics提供了一个向导,能够帮助您将Spartacus lib ...
SAP Spartacus 4.0 的技术变化
在您迁移到 4.0 版库之前,我们强烈建议您切换到新的应用程序结构和新的功能库. 在多个小步骤中进行迁移更容易(迁移到新的应用程序结构,切换到提取的功能库,然后迁移到 4.0),您可以确保在每一步之后 ...
SAP Spartacus 4.0 deprecation 之一 - i18next-xhr-backend
这个库文件在其 Github 仓库上提到,已经 deprecated 了: 在 SAP Spartacus Schematics 里提到,会被 i18next-http-backend 替换: 在 4 ...
SAP Spartacus 4.0 版本因为 hamburger 依赖导致构建出错的问题
build from Schematics 遇到错误消息: SassError: Undefined function. https://github.com/SAP/spartacus/issues ...
SAP Spartacus UI 服务器端渲染的调试启动方式 - debug 模式
首先确认你已经熟悉这篇文章的启动方式:SAP Spartacus develop branch 的服务器端渲染启动方式. 第一步添加一个新的 build script,把 --configurati ...
SAP Spartacus - Progressive Web Applications，渐进式 Web 应用程序
原文 Spartacus 是一种基于 Angular 的 JavaScript 解决方案,主要在浏览器中运行.它是渐进式 Web 应用程序 (PWA) 之一,反过来又代表了响应式网站和应用程序的共生关 ...
SAP Spartacus 服务器端渲染模式下，在 Node.js 服务器端渲染视图的单步调试
入口:在 express-engine.js 文件的 render 函数设置断点: 进入 platform-server.js: 这个文件就是 SAP Spartacus 开启服务器端渲染之后,pac ...

SAP Spartacus 升级时关于 schematics 的更新