Skip to content

Latest commit

 

History

History
72 lines (49 loc) · 4.95 KB

UPDATING.md

File metadata and controls

72 lines (49 loc) · 4.95 KB

Update example dependencies

The dependencies of the example apps (including Angular, Angular Material and Angular CLI) are automatically updated using Renovate.

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.

Since the examples are Angular CLI apps, we can take advantage of ng update to apply migrations.

Follow these steps to align the example apps with new CLI apps.

Note: The following steps assume that the related Angular dependencies have already been updated in 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/ directory, run yarn to ensure the dependencies are installed in the 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/ match the ones in shared/package.json.

  • Follow the steps in the following section to update the rest of the boilerplate files.

Update other boilerplate files

The Angular CLI default setup is updated using ng update. Any necessary changes to boilerplate files will be done automatically through migration schematics.

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. The angular-cli-diff repo can be a useful resource for discovering changes between versions.

  • In the shared/boilerplate/cli/ directory, run the following commands to automatically apply any available migrations to the boilerplate project:

    # 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>

    Note: In order for ng update to work, there must be a node_modules/ directory with installed dependencies inside the 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 script) by means of the shared/boilerplate/.gitignore file.

  • Inspect 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 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/.

  • 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/ directory are copied to the shared/example-scaffold/ directory, which is used when creating new examples (via yarn create-example ...). Only files that would not be considered boilerplate should be added to the example-scaffold/ directory.

  • Run the following command to list all the boilerplate files that are overridden in specific examples.

    node aio/tools/examples/example-boilerplate.js list-overrides

    Inspect each of these files to determine whether they need to be updated.

  • Inspect the changes and determine whether some of them need to be applied to the systemjs boilerplate files.

  • 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.

  • Finally, commit all changes and submit a pull request.