From fd1bfaa8239d092ca532aef2480f40080730c849 Mon Sep 17 00:00:00 2001 From: George Kalpakas Date: Thu, 25 Aug 2022 09:57:24 +0300 Subject: [PATCH] docs(docs-infra): improve docs on updating angular.io and docs examples apps (#47250) Add a new doc, `aio/UPDATING.md`, with instructions on updating the angular.io app to align with the latest Angular CLI/framework/Material. Also, update the instructions on updating the docs examples apps. PR Close #47250 --- aio/UPDATING.md | 42 ++++++++++++++++++++++++++++++++++ aio/tools/examples/UPDATING.md | 42 ++++++++++++++++++++++------------ 2 files changed, 70 insertions(+), 14 deletions(-) create mode 100644 aio/UPDATING.md diff --git a/aio/UPDATING.md b/aio/UPDATING.md new file mode 100644 index 00000000000..9c83258d056 --- /dev/null +++ b/aio/UPDATING.md @@ -0,0 +1,42 @@ +# Update the angular.io app + +The dependencies of the angular.io app (including Angular, Angular Material and Angular CLI) are automatically updated using [Renovate](https://renovatebot.com/). + +However, it is useful to periodically also manually update the app to more closely match (in file layout, configs, etc.) what a new Angular CLI app would look like. +This is typically only needed once for each new major Angular version. + +Since angular.io is an Angular CLI app, we can take advantage of `ng update` to apply migrations. + +Follow these steps to align the angular.io app with new CLI apps. + +> **Note:** +> The following steps assume that the related Angular dependencies have already been updated in [aio/package.json](./package.json) (for example, automatically by Renovate). + +> **Note:** +> All commands shown below are expected to be executed from inside the [aio/](./) directory (unless specified otherwise). + +- Determine (for example, by examining git history) what is the last versions for which this process was performed. + These will be referred to as ``. + If you can't determine these, use arbitrary versions, such as the previous major version. + +- Run the following commands to automatically apply any available migrations to the project: + ```sh + # Ensure dependencies are installed. + yarn install + + # Migrate project to new versions. + yarn ng update @angular/cli --allow-dirty --migrate-only --from= + yarn ng update @angular/core --allow-dirty --migrate-only --from= + yarn ng update @angular/material --allow-dirty --migrate-only --from= + ``` + + > **Note:** + > Depending on the number of changes generated from each `ng update` command, it might make sense to create a separate commit for each update. + +- Inspect [package.json](./package.json) to determine what is the current version of Angular CLI (i.e. `@angular/cli`) used in the app. + This will be referred to as ``. + +- Use the [angular-cli-diff](https://github.com/cexbrayat/angular-cli-diff) repository to discover more changes (which are not automatically applied via `ng update` migrations) between Angular CLI apps of different versions. + Visit https://github.com/cexbrayat/angular-cli-diff/compare/..., inspect the changes between the two versions and apply the ones that make sense to the angular.io source code. + +- Commit all changes and [submit a pull request](../CONTRIBUTING.md#submit-pr). diff --git a/aio/tools/examples/UPDATING.md b/aio/tools/examples/UPDATING.md index 47057d8e134..78141ce813a 100644 --- a/aio/tools/examples/UPDATING.md +++ b/aio/tools/examples/UPDATING.md @@ -1,15 +1,23 @@ # Update example dependencies -Follow these steps to update the examples to the latest versions of Angular (and related dependencies): +The dependencies of the example apps (including Angular, Angular Material and Angular CLI) are automatically updated using [Renovate](https://renovatebot.com/). -- In [shared/package.json](./shared/package.json), bump all the `@angular/*` and `@nguniversal/*` package versions to the version you want to update to and update their peer dependencies (such as `@angular-devkit/*`, `rxjs`, `typescript`, `zone.js`) and other dependencies (e.g. `@types/*`) to the latest compatible versions. +However, it is useful to periodically also manually update the apps to more closely match (in file layout, configs, etc.) what a new Angular CLI app would look like. +This is typically only needed once for each new major Angular version. - > NOTE: - > The [angular-cli-diff](https://github.com/cexbrayat/angular-cli-diff) repo can be a useful resource for discovering what dependency versions are used for a basic CLI app at a specific CLI version. +Since the examples are Angular CLI apps, we can take advantage of `ng update` to apply migrations. -- In the [shared/](./shared) directory, run `yarn` to update the dependencies in the [shared/node_modules/](./shared/node_modules) directory and the [shared/yarn.lock](./shared/yarn.lock) file. +Follow these steps to align the example apps with new CLI apps. -- In the [shared/](./shared) directory, run `yarn sync-deps` to update the dependency versions of the `package.json` files in each sub-folder of [shared/boilerplate/](./shared/boilerplate) to match the ones in [shared/package.json](./shared/package.json). +> **Note:** +> The following steps assume that the related Angular dependencies have already been updated in [shared/package.json](./shared/package.json) (for example, automatically by Renovate). + +- Determine (for example, by examining git history) what is the last versions for which this process was performed. + These will be referred to as ``. + If you can't determine these, use arbitrary versions, such as the previous major version. + +- In the [shared/](./shared) directory, run `yarn` to ensure the dependencies are installed in the [shared/node_modules/](./shared/node_modules) directory. + This command will also ensure that the dependency versions of the `package.json` files in each sub-folder of [shared/boilerplate/](./shared/boilerplate) match the ones in [shared/package.json](./shared/package.json). - Follow the steps in the following section to update the rest of the boilerplate files. @@ -19,26 +27,32 @@ Follow these steps to update the examples to the latest versions of Angular (and The Angular CLI default setup is updated using `ng update`. Any necessary changes to boilerplate files will be done automatically through migration schematics. -> NOTE: +> **Note:** > Migrations affecting source code files will not happen automatically, because `ng update` does not know about all the examples in `aio/content/examples/`. > You have to make these changes (if any) manually. -> Again, the [angular-cli-diff](https://github.com/cexbrayat/angular-cli-diff) repo can be a useful resource for discovering changes between versions. +> The [angular-cli-diff](https://github.com/cexbrayat/angular-cli-diff) repo can be a useful resource for discovering changes between versions. -- In the [shared/boilerplate/cli/](./shared/boilerplate/cli) directory, run the following commands to migrate the project to the current versions of Angular CLI and the Angular framework (updated in previous steps): +- In the [shared/boilerplate/cli/](./shared/boilerplate/cli) directory, run the following commands to automatically apply any available migrations to the boilerplate project: ```sh # Ensure dependencies are installed. yarn install # Migrate project to new versions. - yarn ng update @angular/cli --allow-dirty --migrate-only --from= - yarn ng update @angular/core --allow-dirty --migrate-only --from= + yarn ng update @angular/cli --allow-dirty --migrate-only --from= + yarn ng update @angular/core --allow-dirty --migrate-only --from= ``` - > NOTE: + > **Note:** > In order for `ng update` to work, there must be a `node_modules/` directory with installed dependencies inside the [shared/boilerplate/cli/](./shared/boilerplate/cli) directory. > This `node_modules/` directory is only needed during the update operation and is otherwise ignored (both by git and by the [example-boilerplate.js](./example-boilerplate.js) script) by means of the [shared/boilerplate/.gitignore](./shared/boilerplate/.gitignore) file. -- The previous command made any necessary changes to boilerplate files inside the `cli/` directory, but the same changes need to be applied to the other CLI-based boilerplate directories. +- Inspect [shared/package.json](./shared/package.json) to determine what is the current version of Angular CLI (i.e. `@angular/cli`) used in the example apps. + This will be referred to as ``. + +- Use the [angular-cli-diff](https://github.com/cexbrayat/angular-cli-diff) repository to discover more changes (which are not automatically applied via `ng update` migrations) between Angular CLI apps of different versions. + Visit https://github.com/cexbrayat/angular-cli-diff/compare/..., inspect the changes between the two versions and apply the ones that make sense to the boilerplate files inside [shared/boilerplate/cli/](./shared/boilerplate/cli). + +- The previous steps made any necessary changes to boilerplate files inside the `cli/` directory, but the same changes need to be applied to the other CLI-based boilerplate directories. Inspect the changes in `cli/` and manually apply the necessary ones to other CLI-based boilerplate directories. - Also ensure that any relevant changes in the [shared/boilerplate/cli/](./shared/boilerplate/cli) directory are copied to the [shared/example-scaffold/](./shared/example-scaffold) directory, which is used when creating new examples (via `yarn create-example ...`). @@ -55,4 +69,4 @@ Any necessary changes to boilerplate files will be done automatically through mi - Inspect the changes and determine whether any updates to guides are necessary. For example, if a file is renamed or moved, any guides mentioning that file may need updating to refer to the new name/location. -- Commit all changes to the repository. +- Finally, commit all changes and [submit a pull request](../../../CONTRIBUTING.md#submit-pr).