docs(docs-infra): update instructions for updating docs examples dependencies (#38992)
PR Close #38992
This commit is contained in:
George Kalpakas
Alex Rickabaugh
parent
efe0e03fe1
commit
37ed4bd9ff
|
|
@ -6,6 +6,7 @@ Everything in this folder is part of the documentation project. This includes
|
|||
* the dgeni configuration for converting source files to rendered files that can be viewed in the web site.
|
||||
* the tooling for setting up examples for development; and generating live-example and zip files from the examples.
|
||||
|
||||
<a name="developer-tasks"></a>
|
||||
## Developer tasks
|
||||
|
||||
We use [Yarn](https://yarnpkg.com) to manage the dependencies and to run build tasks.
|
||||
|
|
|
|||
|
|
@ -1,17 +0,0 @@
|
|||
# Docs releases
|
||||
|
||||
This document explains how to update the documentation examples after an Angular release.
|
||||
This is only needed for major and minor versions.
|
||||
|
||||
All the packages for the docs' examples are specified in `/aio/tools/examples/shared/package.json`
|
||||
|
||||
**1)** So within the `shared` folder, you need to issue the following command:
|
||||
|
||||
```
|
||||
$ yarn upgrade-interactive --tilde
|
||||
```
|
||||
|
||||
There, select all the packages that are updated on the new Angular release.
|
||||
|
||||
**2)** Changes to the tsconfig.json?
|
||||
There are several files in `/aio/tools/examples/shared/boilerplate/*/tsconfig.json` (based on the example type).
|
||||
|
|
@ -1,106 +1,157 @@
|
|||
# Overview
|
||||
|
||||
Many of the documentation pages contain snippets of code examples.
|
||||
Extract these snippets from real working example applications, which are stored in subfolders of the `/aio/content/examples` folder.
|
||||
These snippets are extracted from real working example applications, which are stored in sub-folders of the [aio/content/examples/](.) folder.
|
||||
Each example can be built and run independently.
|
||||
Each example also provides e2e specs, which are run as part of our CircleCI legacy build tasks, to verify that the examples continue to work as expected, as changes are made to the core Angular libraries.
|
||||
Each example also provides tests (mostly e2e and occasionally unit tests), which are run as part of our CircleCI `test_docs_examples*` jobs, to verify that the examples continue to work as expected, as changes are made to the core Angular libraries.
|
||||
|
||||
In order to build, run and test these examples independently you need to install dependencies into their sub-folder.
|
||||
Also there are a number of common boilerplate files that are needed to configure each example's project. Maintain these common boilerplate files centrally to reduce the amount of effort if one of them needs to change.
|
||||
In order to build, run and test these examples independently, you need to install dependencies into their sub-folder.
|
||||
Also there are a number of common boilerplate files that are needed to configure each example's project.
|
||||
These common boilerplate files are maintained centrally to reduce the amount of effort if one of them needs to change.
|
||||
|
||||
> **Note for Windows users**
|
||||
>
|
||||
> Setting up the examples involves creating some [symbolic links](https://en.wikipedia.org/wiki/Symbolic_link) (see [here](#symlinked-node_modules) for details).
|
||||
> On Windows, this requires to either have [Developer Mode enabled](https://blogs.windows.com/windowsdeveloper/2016/12/02/symlinks-windows-10) (supported on Windows 10 or newer) or run the setup commands as administrator.
|
||||
|
||||
|
||||
## Boilerplate overview
|
||||
|
||||
As mentioned, many of the documentation pages contain snippets extracted from real example applications.
|
||||
To achieve that, all those applications needs to contain a basic boilerplate.
|
||||
E.g. a `node_modules` folder, `package.json` with scripts, etc.
|
||||
As mentioned above, many of the documentation pages contain snippets extracted from real example applications.
|
||||
To achieve that, all those applications need to contain some basic boilerplate, such as a `node_modules/` folder, a `package.json` file with scripts and dependencies, etc.
|
||||
|
||||
There are also different project types, each with its own boilerplate.
|
||||
For example, there are projects based on the Angular CLI, projects that use AngularJS, Custom Elements, i18n, server-side rendering, etc.
|
||||
(See the [example configuration section](#example-config) below for more info on how to specify the project type.)
|
||||
|
||||
To avoid having to maintain the boilerplate in each example, we use the [example-boilerplate-js](./example-boilerplate.js) script to provide a set of files that works across all the examples of a specific type.
|
||||
|
||||
No one wants to maintain the boilerplate on each example, so the goal of this tool is to provide a set of files that works across all the examples.
|
||||
|
||||
### Boilerplate files
|
||||
|
||||
Inside `/aio/tools/examples/shared/boilerplate` you will find a set of folders representing each project type.
|
||||
Inside [shared/boilerplate/](./shared/boilerplate) there is a sub-folder with boilerplate files for each of the different project types.
|
||||
|
||||
Currently you will find the next project types:
|
||||
Currently, the following project types are supported:
|
||||
|
||||
* cli - For CLI based examples. This is the default one, to be used in the majority of the examples.
|
||||
* getting-started - CLI-based with its own set of styles.
|
||||
* i18n - CLI-based with additional scripts for internationalization.
|
||||
* schematics - CLI-based with additional scripts for building schematics.
|
||||
* service-worker - CLI-based with additional packages and configuration for service workers.
|
||||
* systemjs - Currently in deprecation, only used in a few examples.
|
||||
* testing - CLI-based with additional styles for jasmine testing.
|
||||
* universal - CLI-based with an extra server target.
|
||||
* viewengine - Additional configuration for running CLI-/SystemJS-based examples with `ViewEngine` (the pre-Ivy compiler/renderer).
|
||||
- `cli`: For example apps based on the Angular CLI. This is the default type and is used in the majority of the examples.
|
||||
- `cli-ajs`: For CLI-based examples that also use AngularJS (but not via `@angular/upgrade`).
|
||||
- `elements`: For CLI-based examples that also use `@angular/elements`.
|
||||
- `getting-started`: For the "Getting started" tutorial. Essentially the same as `cli` but with custom CSS styles.
|
||||
- `i18n`: For CLI-based examples that also use internationalization.
|
||||
- `schematics`: For CLI-based examples that include a library with schematics.
|
||||
- `service-worker`: For CLI-based examples that also use `@angular/service-worker`.
|
||||
- `systemjs`: For non-CLI legacy examples using SystemJS. This is deprecated and only used in few examples.
|
||||
- `testing`: For CLI-based examples that are related to unit testing.
|
||||
- `universal`: For CLI-based examples that also use `@nguniversal/express-engine` for SSR.
|
||||
|
||||
There is also a `common` folder that contains files used in all different examples.
|
||||
There are also the following special folders:
|
||||
- `common`: Contains files used in many examples.
|
||||
(See the [next section](#example-config) for info on how to exclude common files in certain examples.)
|
||||
- `viewengine/cli`: Additional configuration for running CLI-based examples with `ViewEngine` (the pre-Ivy compiler/renderer).
|
||||
This applies to all CLI-based examples, such as `cli-ajs`, `elements`, `getting-started`, etc.
|
||||
- `viewengine/systemjs`: Additional configuration for running SystemJS-based examples with `ViewEngine` (the pre-Ivy compiler/renderer).
|
||||
|
||||
### The example-config.json
|
||||
|
||||
Each example is identified by an **example-config.json** configuration file in its root folder.
|
||||
This configuration file indicates what type of boilerplate this example needs.
|
||||
E.g.
|
||||
<a name="example-config"></a>
|
||||
### The `example-config.json`
|
||||
|
||||
Each example is identified by an `example-config.json` configuration file in its root folder.
|
||||
This configuration file indicates what type of boilerplate this example needs and how to test it.
|
||||
For example:
|
||||
|
||||
```json
|
||||
{
|
||||
"projectType": "cli",
|
||||
"useCommonBoilerplate": true
|
||||
"projectType": "cli"
|
||||
}
|
||||
```
|
||||
|
||||
If the file is empty then the default type of cli is assumed.
|
||||
When the boilerplate tooling runs, it will copy into the example folder all of the appropriate files based on the project type.
|
||||
The file is expected to contain a JSON object with zero or more of the following properties:
|
||||
|
||||
- `projectType: string`: One of the supported project types (see above).
|
||||
Default: `"cli"`
|
||||
- `useCommonBoilerplate: boolean`: Whether to include common boilerplate from the [common/](./shared/boilerplate/common) folder.
|
||||
Default: `true`
|
||||
|
||||
**SystemJS-only properties:**
|
||||
- `build: string`: The npm script to run in order to build the example app.
|
||||
Default: `"build"`
|
||||
- `run: string`: The npm script to run in order to serve the example app (so that e2e test can be run against it).
|
||||
Default `"serve:e2e"`
|
||||
|
||||
**CLI-only properties:**
|
||||
- `tests: object[]`: An array of objects, each specifying a test command. This can be used to run multiple test commands in series (for example, to run unit and e2e tests).
|
||||
The commands are specified as `{cmd: string, args: string[]}` and must be in a format that could be passed to Node.js' `child_process.spawn(cmd, args)`. You can use a special `{PORT}` placeholder, that will be replaced with the port on which the app is served during the actual test.
|
||||
Default:
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"cmd": "yarn",
|
||||
"args": [
|
||||
"e2e",
|
||||
"--prod",
|
||||
"--protractor-config=e2e/protractor-puppeteer.conf.js",
|
||||
"--no-webdriver-update",
|
||||
"--port={PORT}"
|
||||
]
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
An empty `example-config.json` file is equivalent with `{"projectType": "cli"}`.
|
||||
|
||||
|
||||
<a name="symlinked-node_modules"></a>
|
||||
### A node_modules to share
|
||||
### A `node_modules/` to share
|
||||
|
||||
With all the boilerplate files in place, the only missing piece are the installed packages.
|
||||
For that you have a `/aio/tools/examples/shared/package.json` which contains **all** the packages needed to run all the examples through all different boilerplates.
|
||||
With all the boilerplate files in place, the only missing piece is the installed packages.
|
||||
For that we have [shared/package.json](./shared/package.json), which contains **all** the packages needed to run any example type.
|
||||
|
||||
After installing these dependencies, a `node_modules/` folder will be created at `/aio/tools/examples/shared/node_modules/`.
|
||||
Upon installing these dependencies, a [shared/node_modules/](./shared/node_modules) folder is created.
|
||||
This folder will be **symlinked** into each example.
|
||||
So it is not a copy like the other boilerplate files.
|
||||
|
||||
### End to end tests
|
||||
|
||||
End to end changes between boilerplates.
|
||||
### End-to-end tests
|
||||
|
||||
For CLI applications, create a `app.e2e-spec.ts` inside the `e2e` folder.
|
||||
The tooling will run `ng e2e` for each CLI based examples.
|
||||
End-to-end infrastructure is slightly different between CLI- and SystemJS-based examples.
|
||||
|
||||
For SystemJS, each example contains an `e2e-spec.ts` file.
|
||||
You can find all the related configuration files in the `/aio/tools/examples/shared` folder.
|
||||
For CLI-based examples, create an `app.e2e-spec.ts` file inside the `e2e/` folder.
|
||||
This will be picked up by the default testing command (see the [example configuration section](#example-config) above).
|
||||
If you are using a custom test command, make sure e2e specs are picked up (if applicable).
|
||||
|
||||
### example-boilerplate.js
|
||||
For SystemJS-based examples, create an `e2e-spec.ts` file inside the example root folder.
|
||||
These apps will be tested with the following command:
|
||||
|
||||
This script installs all the dependencies that are shared among all the examples, creates the `node_modules` symlinks and copy all the boilerplate files where needed.
|
||||
It won't do anything about stackblitz nor e2e tests.
|
||||
```sh
|
||||
yarn protractor aio/tools/examples/shared/protractor.config.js \
|
||||
--specs=<example-folder>/e2e-spec.ts \
|
||||
--params.appDir=<example-folder>
|
||||
```
|
||||
|
||||
|
||||
### `example-boilerplate.js`
|
||||
|
||||
The [example-boilerplate.js](./example-boilerplate.js) script installs the dependencies for all examples, creates the `node_modules/` symlinks and copies the necessary boilerplate files into example folders.
|
||||
|
||||
It also contains a function to remove all the boilerplate.
|
||||
It uses a `git clean -xdf` to do the job.
|
||||
It will remove all files that don't exist in the git repository, **including any new file that you are working on that hasn't been stage yet.**
|
||||
So be sure to save your work before removing the boilerplate.
|
||||
It uses `git clean -xdf` to do the job.
|
||||
It will remove all files that are not tracked by git, **including any new files that you are working on that haven't been stageg yet.**
|
||||
So, be sure to commit your work before removing the boilerplate.
|
||||
|
||||
### run-example-e2e.js
|
||||
|
||||
This script will find all the `e2e-spec.ts` files and run them.
|
||||
### `run-example-e2e.js`
|
||||
|
||||
To not run all tests, you can use the `--filter=name` flag to run the example's e2e that contains that name.
|
||||
The [run-example-e2e.js](./run-example-e2e.js) script will find and run the e2e tests for all examples.
|
||||
Although it only runs e2e tests by default, it can be configured to run any test command (for CLI-based examples) by using the `tests` property of the [example-config.json](#example-config) file.
|
||||
It is named `*-e2e` for historical reasons, but it is not limited to running e2e tests.
|
||||
|
||||
It also has an optional `--setup` flag to run the `example-boilerplate.js` script and install the latest `webdriver`.
|
||||
See [aio/README.md](../../README.md#developer-tasks) for the available command-line options.
|
||||
|
||||
Running the script will create an `aio/protractor-results.txt` file with the results of the tests.
|
||||
|
||||
It will create a `/aio/protractor-results.txt` file when it finishes running tests.
|
||||
|
||||
### Updating example dependencies
|
||||
|
||||
With every major release, we update the examples to be on the latest version.
|
||||
The following steps to update are:
|
||||
|
||||
* In the `shared/package.json` file, bump all the `@angular/*`, `@angular-devkit/*`, `rxjs`, `typescript`, and `zone.js` package versions to the version that corresponds with the [framework version](../../../package.json).
|
||||
* In the `shared` folder, run `yarn` to update the dependencies for the shared `node_modules` and the `yarn.lock` file.
|
||||
* In the `boilerplate` folder, go through each sub-folder and update the `package.json` dependencies if one is present.
|
||||
* Follow the [update guide](./shared/boilerplate/UPDATING_CLI.md) to update the common files used in the examples based on project type.
|
||||
With every major Angular release, we update the examples to be on the latest version.
|
||||
See [UPDATING.md](./UPDATING.md) for instructions.
|
||||
|
|
|
|||
|
|
@ -0,0 +1,55 @@
|
|||
# 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.
|
||||
|
||||
- In the [shared/](./shared) folder, run `yarn` to update the dependencies in the [shared/node_modules/](./shared/node_modules) folder and the [shared/yarn.lock](./shared/yarn.lock) file.
|
||||
|
||||
- In the [shared/boilerplate/](./shared/boilerplate) folder, go through each sub-folder and update the dependency versions in all `package.json` files to 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.
|
||||
|
||||
|
||||
## 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.
|
||||
|
||||
- In the [shared/boilerplate/cli/](./shared/boilerplate/cli) folder, run the following commands to migrate the the project to the current versions of Angular CLI and the Angular framework (updated in previous steps):
|
||||
```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>
|
||||
|
||||
# Remove `node_modules/` and `yarn.lock`.
|
||||
rm -rf node_modules yarn.lock
|
||||
```
|
||||
|
||||
> 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 must be subsequently removed to avoid its being copied into all CLI-based examples.
|
||||
|
||||
- The previous command made any necessary changes to boilerplate files inside the `cli/` folder, but the same changes need to be applied to the other CLI-based boilerplate folders.
|
||||
Inspect the changes in `cli/` and manually apply the necessary ones to other CLI-based boilerplate folders.
|
||||
|
||||
- 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.
|
||||
|
|
@ -1,52 +0,0 @@
|
|||
# How to update the CLI project
|
||||
|
||||
The Angular CLI default setup is updated using `ng update`.
|
||||
Any necessary file changes will be done automatically through migration schematics.
|
||||
|
||||
In the `cli` folder, update the Angular CLI depedencies to the latest version:
|
||||
|
||||
```
|
||||
ng update @angular/cli --next
|
||||
```
|
||||
|
||||
Then update the Angular Framework dependencies to the latest version:
|
||||
|
||||
```
|
||||
ng update @angular/core --next
|
||||
```
|
||||
|
||||
Commit any changes to the `cli` folder to the repository.
|
||||
|
||||
## Updating other CLI-based projects
|
||||
|
||||
Along with the boilerplate files for the `cli` folder, the other cli-based projects need to be updated also. Each cli-based project has slightly modified files specific to the project type.
|
||||
Make sure any necessary changes to these projects are made also to be in alignment with the `cli` project files.
|
||||
|
||||
The specific changes to each project type are listed below:
|
||||
|
||||
* i18n
|
||||
- angular.json
|
||||
- Includes additional configurations for `build`, `serve`, and `e2e` for different locales
|
||||
- package.json
|
||||
- Includes custom scripts for building and serving different locales
|
||||
* ivy
|
||||
- cli/tsconfig.app.json
|
||||
- Includes an `angularCompilerOptions` object with `enableIvy` set to `true`
|
||||
* schematics
|
||||
- angular.json
|
||||
- Includes a `my-lib` project that contains a library with example schematics
|
||||
* service-worker
|
||||
- angular.json
|
||||
- Has `serviceWorker` set to `true` in the `production` build target
|
||||
- package.json
|
||||
- Includes `@angular/service-worker` in `dependencies`
|
||||
* testing
|
||||
- angular.json
|
||||
- Includes `src/test.css` in the `styles` for the `test` target
|
||||
* universal
|
||||
- angular.json
|
||||
- Includes a `server` target in the `build` architect runners
|
||||
- package.json
|
||||
- Includes custom scripts for building the `server`
|
||||
- Includes additional `dependencies` on `@angular/platform-server`, `@nguniversal/express-engine`, and `express`
|
||||
- Includes additional `devDependencies` on `@nguniversal/builders` and `@types/express`
|
||||
Loading…
Reference in New Issue