You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
chore: move update-schematic.md to cdk schematics (#14252)
* Since the CDK now contains the code-foundation for `ng-update`, the explanation/description document should live there.
* Wraps the markdown lines, so that it's easier to make changes.
Copy file name to clipboardExpand all lines: src/cdk/schematics/ng-update/update-schematic.md
+75-30Lines changed: 75 additions & 30 deletions
Original file line number
Diff line number
Diff line change
@@ -1,34 +1,54 @@
1
-
2
1
# ng-update schematic
2
+
3
+
**Note** The CDK ng-update schematic is the foundation for the Angular Material update
4
+
schematic. This is achieved by making the ng-update code for the CDK as abstract as possible.
5
+
6
+
This means that this document also applies for the Angular Material `ng-update`.
7
+
8
+
---
3
9
4
-
The `ng-update` schematic consists of multiple migration entry-points where every entry-point targets a specific Angular Material version.
5
-
6
-
As of right now, we have two migration entry-points that handle the breaking changes for the given target version:
10
+
The `ng-update` schematic consists of multiple migration entry-points where every entry-point
11
+
targets a specific Angular CDK or Angular Material version.
12
+
13
+
14
+
As of right now, we have two migration entry-points that handle the breaking changes for the
15
+
given target version:
7
16
8
17
| Target Version | Description |
9
18
|----------------|-------------|
10
-
| V6 | Upgrade from any version to Angular Material 6.0.0 |
11
-
| V7 | Upgrade from any version to Angular Material 7.0.0 |
19
+
| V6 | Upgrade from any version to v6.0.0 |
20
+
| V7 | Upgrade from any version to v7.0.0 |
12
21
13
-
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.
22
+
Note that the migrations run _in order_ if multiple versions are transitively targeted. For
23
+
example, consider an application which uses Angular Material v5.0.0. In case the developer runs
24
+
`ng update`, the Angular CLI **only** installs V7 and runs the V6 and V7 migrations in order.
25
+
26
+
This shows that the we technically need to keep all migrations from V5 in this code base, because
27
+
the CLI usually only installs the latest version and expects all version migrations to be present.
14
28
15
29
## Update concept
16
30
17
-
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.
31
+
The goal of the update schematic is to automatically migrate code that is affected by breaking
32
+
changes of the target version. Most of the time, we can apply such automatic migrations, but
33
+
there are also a few breaking changes that cannot be migrated automatically.
18
34
19
-
In that case, our goal should be to notify the developer about the breaking change that needs developer attention.
35
+
In that case, our goal should be to notify the developer about the breaking change that needs
36
+
developer attention.
20
37
21
38
## Transforming TypeScript files
22
39
23
-
In order to automatically migrate TypeScript source files, we take advantage of the `TSLint` toolkit which involves creating custom rules that allow us to:
40
+
In order to automatically migrate TypeScript source files, we take advantage of the `tslint`
41
+
which allows us to create custom rules that can:
24
42
25
43
* Easily `visit` specific types of TypeScript nodes (e.g. `visitClassDeclaration`)
26
44
* Structure migrations based on the _upgrade data_ or type of migration (different TSLint rules)
27
45
* Easily apply replacements / fixes for specific TypeScript nodes.
28
46
* Easily report breaking changes at TypeScript nodes that cannot be migrated automatically
29
47
* Double check for rule migrations (TSLint always runs rule again after migrations have been applied)
30
48
31
-
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:
49
+
There also other various concepts for transforming TypeScript source files, but most of them
50
+
don't provide a simple API for replacements and reporting. Read more about the possible
51
+
approaches below:
32
52
33
53
|Description | Evaluation |
34
54
|------------|------------|
@@ -38,11 +58,17 @@ There also other various concepts for transforming TypeScript source files, but
38
58
39
59
## ## Transforming CSS and HTML files
40
60
41
-
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.
42
-
43
-
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.
44
-
45
-
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,
61
+
Since `TSLint` allows us to only visit TypeScript nodes, we can technically just apply migrations
62
+
for inline styles or templates which are part of the TypeScript AST. In our case, the update
63
+
schematic should also apply migrations for external templates or styles. In order to archive
64
+
this with TSLint, we have a customized implementation of a `TSLint.RuleWalker`. The custom
65
+
RuleWalker which is called `ComponentWalker` determines external templates and stylesheets from
66
+
the _component/directive_ metadata.
67
+
68
+
The given resource files will then be wrapped inside of an in-memory TypeScript source file that
69
+
can be applied to the rule walker. This ensures that only referenced resource files will be
70
+
migrated and also allows us to take advantage of the simple replacement and reporting API from
71
+
TSLint.
46
72
47
73
This also makes the rule walker API consistent with the handling of inline resource files.
The upgrade data for migrations is separated based on the target version. This is necessary in order to allow migrations run sequentially. For example:
86
+
The upgrade data for migrations is separated based on the target version. This is necessary in
87
+
order to allow migrations run sequentially. For example:
61
88
62
89
* In V6: `onChange` has been renamed to `changed`
63
90
* In V7: `changed` has been renamed to `onValueChange`
64
91
65
-
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`_
92
+
If we would not run the migrations in order, or don't separate the upgrade data, we would not be
93
+
able to properly handle the migrations for each target version. e.g. someone is on
94
+
5.0.0 and *only* wants to upgrade to 6.0.0. In that case he would end up with `onValueChange`
95
+
because the non-separated upgrade data would just include: _`onChange` => `onValueChange`_
66
96
67
-
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:
97
+
Also besides separating the upgrade data based on the target version, we split the upgrade data
98
+
based on the type of code that is affected by these migrations:
68
99
69
100
* See here: [src/lib/schematics/update/material/data](https://github.com/angular/material2/tree/master/src/lib/schematics/update/material/data)
70
101
71
102
### Adding upgrade data
72
103
73
-
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.
104
+
Adding upgrade data is now a **mandatory** step before breaking changes should be merged
105
+
into `upstream`. For simple and common breaking changes, there should be already an upgrade
106
+
data file that just needs the new change inserted.
74
107
75
-
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.
108
+
In case there is no upgrade data for a breaking change, we need to evaluate if there should be
109
+
a single `misc` migration rule that is tied to that specific breaking change, or if we should
110
+
create a new migration rule in a more generic way.
76
111
77
112
---
78
113
79
114
**Example**: Adding upgrade data for a property rename
80
115
**Scenario**: In Angular Material V7.0.0, we rename `MatRipple#color` to `MatRipple#newColor`.
81
116
82
-
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`.
117
+
First, look for an existing upgrade data file that covers similar breaking changes. In that case
118
+
an existing upgrade data file for `property-names` already exists. Insert the new breaking change
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.
141
+
Once the data is inserted into the upgrade data file, the update schematic will properly migrate
142
+
`MatRipple#color` to `MatRipple#newColor` if someone upgrades to Angular Material V7.0.0.
105
143
106
-
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.
144
+
But that's not all. It's encouraged to add a test-case for the new migration data. In this case,
145
+
a test case already exists for the type of migration and we just need to add our breaking change
146
+
to it. Read more about adding a test case in the next section.
107
147
108
148
### Adding a breaking change to a test case
109
149
110
-
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.
150
+
Considering we added a breaking change to the update schematic, it's encouraged to add a proper
151
+
test case for the new change that has been added.
111
152
112
-
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.
153
+
In the scenario where a property from `MatRipple` has been renamed in V7, we don't need to create
154
+
a new test-case file because there is already a test case for the `property-names` upgrade data.
155
+
In that case, we just need to add the breaking change to the existing test case.
**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.
203
+
**Note**: The `_input.ts` file will be just transformed by the V7 migrations and compared to
204
+
the `_expected_output.ts` file. This means that it's necessary to also include the no longer
205
+
valid mock declarations to the expected output file.
0 commit comments