docs(docs-infra): improve docs on updating angular.io and docs exampl…

…es apps (angular#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 angular#47250

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 `<FROM_VERSION_*>`.
+  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=<FROM_VERSION_CLI>
+  yarn ng update @angular/core --allow-dirty --migrate-only --from=<FROM_VERSION_ANGULAR>
+  yarn ng update @angular/material --allow-dirty --migrate-only --from=<FROM_VERSION_MATERIAL>
+  ```
+
+  > **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 `<TO_VERSION_CLI>`.
+
+- 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/<FROM_VERSION_CLI>...<TO_VERSION_CLI>, 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).

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 `<FROM_VERSION_*>`.
+  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=<previous-cli-version>
-  yarn ng update @angular/core --allow-dirty --migrate-only --from=<previous-core-version>
+  yarn ng update @angular/cli --allow-dirty --migrate-only --from=<FROM_VERSION_CLI>
+  yarn ng update @angular/core --allow-dirty --migrate-only --from=<FROM_VERSION_ANGULAR>
   ```
 
-  > 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 `<TO_VERSION_CLI>`.
+
+- 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/<FROM_VERSION_CLI>...<TO_VERSION_CLI>, 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).