Skip to content

chore: move update-schematic.md to cdk schematics #14252

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Nov 27, 2018
Merged

chore: move update-schematic.md to cdk schematics #14252

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
105 changes: 75 additions & 30 deletions .../schematics/ng-update/update-schematic.md → .../schematics/ng-update/update-schematic.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,34 +1,54 @@

# ng-update schematic

**Note** The CDK ng-update schematic is the foundation for the Angular Material update
schematic. This is achieved by making the ng-update code for the CDK as abstract as possible.

This means that this document also applies for the Angular Material `ng-update`.

---

The `ng-update` schematic consists of multiple migration entry-points where every entry-point targets a specific Angular Material version.

As of right now, we have two migration entry-points that handle the breaking changes for the given target version:
The `ng-update` schematic consists of multiple migration entry-points where every entry-point
targets a specific Angular CDK or Angular Material version.


As of right now, we have two migration entry-points that handle the breaking changes for the
given target version:

| Target Version | Description |
|----------------|-------------|
| V6 | Upgrade from any version to Angular Material 6.0.0 |
| V7 | Upgrade from any version to Angular Material 7.0.0 |
| V6 | Upgrade from any version to v6.0.0 |
| V7 | Upgrade from any version to v7.0.0 |

Note that the migrations run in order if multiple versions are transitively targeted. For example, consider an application which uses Angular Material v5.0.0. In case the developer runs `ng update`, the Angular CLI installs V7 and runs the V6 and V7 migrations in order.
Note that the migrations run _in order_ if multiple versions are transitively targeted. For
example, consider an application which uses Angular Material v5.0.0. In case the developer runs
`ng update`, the Angular CLI **only** installs V7 and runs the V6 and V7 migrations in order.

This shows that the we technically need to keep all migrations from V5 in this code base, because
the CLI usually only installs the latest version and expects all version migrations to be present.

## Update concept

The goal of the update schematic is to automatically migrate code that is affected by breaking changes of the target version. Most of the time, we can apply such automatic migrations, but there are also a few breaking changes that cannot be migrated automatically.
The goal of the update schematic is to automatically migrate code that is affected by breaking
changes of the target version. Most of the time, we can apply such automatic migrations, but
there are also a few breaking changes that cannot be migrated automatically.

In that case, our goal should be to notify the developer about the breaking change that needs developer attention.
In that case, our goal should be to notify the developer about the breaking change that needs
developer attention.

## Transforming TypeScript files

In order to automatically migrate TypeScript source files, we take advantage of the `TSLint` toolkit which involves creating custom rules that allow us to:
In order to automatically migrate TypeScript source files, we take advantage of the `tslint`
which allows us to create custom rules that can:

* Easily `visit` specific types of TypeScript nodes (e.g. `visitClassDeclaration`)
* Structure migrations based on the _upgrade data_ or type of migration (different TSLint rules)
* Easily apply replacements / fixes for specific TypeScript nodes.
* Easily report breaking changes at TypeScript nodes that cannot be migrated automatically
* Double check for rule migrations (TSLint always runs rule again after migrations have been applied)

There also other various concepts for transforming TypeScript source files, but most of them don't provide a simple API for replacements and reporting. Read more about the possible approaches below:
There also other various concepts for transforming TypeScript source files, but most of them
don't provide a simple API for replacements and reporting. Read more about the possible
approaches below:

|Description | Evaluation |
|------------|------------|
Expand All @@ -38,11 +58,17 @@ There also other various concepts for transforming TypeScript source files, but

## ## Transforming CSS and HTML files

Since `TSLint` allows us to only visit TypeScript nodes, we can technically just apply migrations for inline styles or templates which are part of the TypeScript AST.

But for our update schematic, we also want to apply migrations for external templates or styles. In order to archive this with TSLint, we have a customized implementation of a `TSLint.RuleWalker`. The custom RuleWalker which is called `ComponentWalker` determines external templates and stylesheets from the _component/directive_ metadata.

The given resource files will then be wrapped inside of an in-memory TypeScript source file that can be applied to the rule walker. This ensures that only referenced resource files will be migrated and also allows us to take advantage of the simple replacement and reporting API from TSLint,
Since `TSLint` allows us to only visit TypeScript nodes, we can technically just apply migrations
for inline styles or templates which are part of the TypeScript AST. In our case, the update
schematic should also apply migrations for external templates or styles. In order to archive
this with TSLint, we have a customized implementation of a `TSLint.RuleWalker`. The custom
RuleWalker which is called `ComponentWalker` determines external templates and stylesheets from
the _component/directive_ metadata.

The given resource files will then be wrapped inside of an in-memory TypeScript source file that
can be applied to the rule walker. This ensures that only referenced resource files will be
migrated and also allows us to take advantage of the simple replacement and reporting API from
TSLint.

This also makes the rule walker API consistent with the handling of inline resource files.

Expand All @@ -57,31 +83,42 @@ visitExternalTemplate(node: ts.SourceFile) {

### Upgrade data for target versions

The upgrade data for migrations is separated based on the target version. This is necessary in order to allow migrations run sequentially. For example:
The upgrade data for migrations is separated based on the target version. This is necessary in
order to allow migrations run sequentially. For example:

* In V6: `onChange` has been renamed to `changed`
* In V7: `changed` has been renamed to `onValueChange`

If we would not run the migrations in order, or don't separate the upgrade data, we wouldn't be able to properly handle the migrations for each target version. e.g. someone is on 5.0.0 and *only* wants to upgrade to 6.0.0. In that case he would end up with `onValueChange` because the non-separated upgrade data would just include: _`onChange` >`onValueChange`_
If we would not run the migrations in order, or don't separate the upgrade data, we would not be
able to properly handle the migrations for each target version. e.g. someone is on
5.0.0 and *only* wants to upgrade to 6.0.0. In that case he would end up with `onValueChange`
because the non-separated upgrade data would just include: _`onChange` => `onValueChange`_

Also besides separating the upgrade data based on the target version, we split the upgrade data based on the type of code that is affected by these migrations:
Also besides separating the upgrade data based on the target version, we split the upgrade data
based on the type of code that is affected by these migrations:

* See here: [src/lib/schematics/update/material/data](https://github.com/angular/material2/tree/master/src/lib/schematics/update/material/data)

### Adding upgrade data

Adding upgrade data is now an essential step before breaking changes should be merged into `upstream`. For simple and common breaking changes, there should be already an upgrade data file that just needs the new change inserted.
Adding upgrade data is now a **mandatory** step before breaking changes should be merged
into `upstream`. For simple and common breaking changes, there should be already an upgrade
data file that just needs the new change inserted.

In case there is no upgrade data for a breaking change, we need to evaluate if there should be a single `misc` migration rule that is tied to that specific breaking change, or if we should create a new migration rule in a more generic way.
In case there is no upgrade data for a breaking change, we need to evaluate if there should be
a single `misc` migration rule that is tied to that specific breaking change, or if we should
create a new migration rule in a more generic way.

---

**Example**: Adding upgrade data for a property rename
**Scenario**: In Angular Material V7.0.0, we rename `MatRipple#color` to `MatRipple#newColor`.

First, look for an existing upgrade data file that covers similar breaking changes. In that case an existing upgrade data file for `property-names` already exists. Insert the new breaking change within the proper `VersionTarget`.
First, look for an existing upgrade data file that covers similar breaking changes. In that case
an existing upgrade data file for `property-names` already exists. Insert the new breaking change
within the proper `VersionTarget`.

_src/lib/schematics/update/material/data/property-names.ts_
_src/lib/schematics/ng-update/material/data/property-names.ts_
```ts
export const propertyNames: VersionChanges<MaterialPropertyNameData> = {
[TargetVersion.V7]: [
Expand All @@ -101,17 +138,23 @@ export const propertyNames: VersionChanges<MaterialPropertyNameData> = {
...
};
```
Once the data is inserted into the upgrade data file, the update schematic will properly migrate `MatRipple#color` to `MatRipple#newColor` if someone upgrades to Angular Material V7.0.0.
Once the data is inserted into the upgrade data file, the update schematic will properly migrate
`MatRipple#color` to `MatRipple#newColor` if someone upgrades to Angular Material V7.0.0.

But that's not all. It's encouraged to add a test-case for the new migration data. In this case, a test case already exists for the type of migration and we just need to add our breaking change to it. Read more about adding a test case in the next section.
But that's not all. It's encouraged to add a test-case for the new migration data. In this case,
a test case already exists for the type of migration and we just need to add our breaking change
to it. Read more about adding a test case in the next section.

### Adding a breaking change to a test case

Considering we added a breaking change to the update schematic, it's encouraged to add a proper test case for the new change that has been added.
Considering we added a breaking change to the update schematic, it's encouraged to add a proper
test case for the new change that has been added.

In the scenario where a property from `MatRipple` has been renamed in V7, we don't need to create a new test-case file because there is already a test case for the `property-names` upgrade data. In that case, we just need to add the breaking change to the existing test case.
In the scenario where a property from `MatRipple` has been renamed in V7, we don't need to create
a new test-case file because there is already a test case for the `property-names` upgrade data.
In that case, we just need to add the breaking change to the existing test case.

_src/lib/schematics/update/test-cases/v7/property-names_input.ts_
_src/lib/schematics/ng-update/test-cases/v7/property-names_input.ts_
```ts
...

Expand All @@ -134,7 +177,7 @@ class A implements OnInit {
}
```

_src/lib/schematics/update/test-cases/v7/property-names_expected_output.ts_
_src/lib/schematics/ng-update/test-cases/v7/property-names_expected_output.ts_
```ts
...

Expand All @@ -157,4 +200,6 @@ class A implements OnInit {
}
```

**Note**: The `_input.ts` file will be just transformed by the V7 migrations and compared to the `_expected_output.ts` file. This means that it's necessary to also include the no longer valid mock declarations to the expected output file.
**Note**: The `_input.ts` file will be just transformed by the V7 migrations and compared to
the `_expected_output.ts` file. This means that it's necessary to also include the no longer
valid mock declarations to the expected output file.