iSharkFly-Docs
/
angular-docs-cn
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
angular-docs-cn/aio/tools/examples/UPDATING.md

56 lines
4.0 KiB
Markdown
Raw Normal View History

docs(docs-infra): update instructions for updating docs examples dependencies (#38992) PR Close #38992
2020-09-27 06:37:41 -04:00
# Update example dependencies
Follow these steps to update the examples to the latest versions of Angular (and related dependencies):
- 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.
> 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.
build(docs-infra): add a tool to create new examples (#39283) This tool can be run from anywhere in the aio folder as: ```sh yarn create-example <example-name> ``` It will create some basic scaffold files to get the example started. After creation the developer should then use `yarn boilerplate:add` or similar to ensure that the example can be run and tested. You can optionally provide an absolute path to a pre-existing CLI project and it will copy over appropriate files (ignoring boilerplate) to the newly created example. ```sh yarn create-example <example-name> /path/to/other/cli/project ``` Fixes #39275 PR Close #39283
2020-10-15 07:05:14 -04:00
- 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.
docs(docs-infra): update instructions for updating docs examples dependencies (#38992) PR Close #38992
2020-09-27 06:37:41 -04:00
build(docs-infra): add a tool to create new examples (#39283) This tool can be run from anywhere in the aio folder as: ```sh yarn create-example <example-name> ``` It will create some basic scaffold files to get the example started. After creation the developer should then use `yarn boilerplate:add` or similar to ensure that the example can be run and tested. You can optionally provide an absolute path to a pre-existing CLI project and it will copy over appropriate files (ignoring boilerplate) to the newly created example. ```sh yarn create-example <example-name> /path/to/other/cli/project ``` Fixes #39275 PR Close #39283
2020-10-15 07:05:14 -04:00
- 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).
docs(docs-infra): update instructions for updating docs examples dependencies (#38992) PR Close #38992
2020-09-27 06:37:41 -04:00
- 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.
> Again, the [angular-cli-diff](https://github.com/cexbrayat/angular-cli-diff) repo can be a useful resource for discovering changes between versions.
build(docs-infra): add a tool to create new examples (#39283) This tool can be run from anywhere in the aio folder as: ```sh yarn create-example <example-name> ``` It will create some basic scaffold files to get the example started. After creation the developer should then use `yarn boilerplate:add` or similar to ensure that the example can be run and tested. You can optionally provide an absolute path to a pre-existing CLI project and it will copy over appropriate files (ignoring boilerplate) to the newly created example. ```sh yarn create-example <example-name> /path/to/other/cli/project ``` Fixes #39275 PR Close #39283
2020-10-15 07:05:14 -04:00
- In the [shared/boilerplate/cli/](./shared/boilerplate/cli) directory, run the following commands to migrate the the project to the current versions of Angular CLI and the Angular framework (updated in previous steps):
docs(docs-infra): update instructions for updating docs examples dependencies (#38992) PR Close #38992
2020-09-27 06:37:41 -04:00
```sh
# Ensure dependencies are installed.
yarn install
# Migrate project to new versions.
yarn ng update @angular/cli --migrate-only --from=<previous-cli-version>
yarn ng update @angular/core --migrate-only --from=<previous-core-version>
```
> 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.
build(docs-infra): simplify update workflow for CLI-based docs examples boilerplate (#38992) When updating the boilerplate for CLI-based docs examples, one needed to install dependencies inside the `aio/tools/examples/shared/boilerplate/cli/` directory, which resulted in a `node_modules/` directory and a `yarn.lock` file. These were not supposed to be part of the boilerplate, so they had to be manually removed after the boilerplate was updated. This commit simplifies the workflow by allowing boilerplate files to be ignored (both by git and the `example-boilerplate.js` script) via a `.gitignore` file. This way, it is no longer necessary to manually remove the unneeded directories/files. PR Close #38992
2020-09-27 06:37:43 -04:00
> 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.
docs(docs-infra): update instructions for updating docs examples dependencies (#38992) PR Close #38992
2020-09-27 06:37:41 -04:00
build(docs-infra): add a tool to create new examples (#39283) This tool can be run from anywhere in the aio folder as: ```sh yarn create-example <example-name> ``` It will create some basic scaffold files to get the example started. After creation the developer should then use `yarn boilerplate:add` or similar to ensure that the example can be run and tested. You can optionally provide an absolute path to a pre-existing CLI project and it will copy over appropriate files (ignoring boilerplate) to the newly created example. ```sh yarn create-example <example-name> /path/to/other/cli/project ``` Fixes #39275 PR Close #39283
2020-10-15 07:05:14 -04:00
- 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 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 ...`).
Only files that would not be considered boilerplate should be added to the `example-scaffold/` directory.
docs(docs-infra): update instructions for updating docs examples dependencies (#38992) PR Close #38992
2020-09-27 06:37:41 -04:00
- Ensure any changes to [cli/tslint.json](./shared/boilerplate/cli/tslint.json) are ported over to [systemjs/tslint.json](./shared/boilerplate/systemjs/tslint.json) and also [aio/content/examples/tslint.json](../../content/examples/tslint.json).
This last part is important, since this file is used to lint example code on CI.
- 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.
- Commit all changes to the repository.