release: cut the v11.0.0-next.3 release

* Make url and params optional in runBenchmark
* Make url optional in openBrowser
* Remove unused code from runBenchmark

PR Close #38941

.circleci/config.yml

@@ -653,8 +653,10 @@ jobs:
           name: Starting Saucelabs tunnel service
           command: ./tools/saucelabs/sauce-service.sh run
           background: true
-      - run: yarn tsc -p packages
-      - run: yarn tsc -p modules
+      # add module umd tsc compile option so the test can work
+      # properly in the legacy browsers
+      - run: yarn tsc -p packages --module UMD
+      - run: yarn tsc -p modules --module UMD
       - run: yarn bazel build //packages/zone.js:npm_package
       # Build test fixtures for a test that rely on Bazel-generated fixtures. Note that disabling
       # specific tests which are reliant on such generated fixtures is not an option as SystemJS
@@ -747,6 +749,8 @@ jobs:
              cp dist/bin/packages/zone.js/npm_package/bundles/zone-patch-electron.umd.js ./packages/zone.js/test/extra/ &&
              yarn --cwd packages/zone.js electrontest
       - run: yarn --cwd packages/zone.js jesttest
+      - run: yarn --cwd packages/zone.js/test/typings install --frozen-lockfile --non-interactive
+      - run: yarn --cwd packages/zone.js/test/typings test
 
   # Windows jobs
   # Docs: https://circleci.com/docs/2.0/hello-world-windows/

.github/ISSUE_TEMPLATE/1-bug-report.md

@@ -1,5 +1,5 @@
 ---
-name: "\U0001F41EBug report"
+name: "\U0001F41E Bug report"
 about: Report a bug in the Angular Framework
 ---
 <!--🔅🔅🔅🔅🔅🔅🔅🔅🔅🔅🔅🔅🔅🔅🔅🔅🔅🔅🔅🔅🔅🔅🔅🔅🔅🔅🔅🔅🔅🔅🔅

.github/ISSUE_TEMPLATE/2-feature-request.md

@@ -1,5 +1,5 @@
 ---
-name: "\U0001F680Feature request"
+name: "\U0001F680 Feature request"
 about: Suggest a feature for Angular Framework
 
 ---

.github/ISSUE_TEMPLATE/5-support-request.md

@@ -1,5 +1,5 @@
 ---
-name: "❓Support request"
+name: "❓ Support request"
 about: Questions and requests for support
 
 ---

.github/ISSUE_TEMPLATE/6-angular-cli.md

@@ -1,5 +1,5 @@
 ---
-name: "\U0001F6E0️Angular CLI"
+name: "\U0001F6E0️ Angular CLI"
 about: Issues and feature requests for Angular CLI
 
 ---

.github/ISSUE_TEMPLATE/7-angular-components.md

@@ -1,5 +1,5 @@
 ---
-name: "\U0001F48EAngular Components"
+name: "\U0001F48E Angular Components"
 about: Issues and feature requests for Angular Components
 
 ---

.github/angular-robot.yml

@@ -68,6 +68,7 @@ merge:
       - "packages/**/integrationtest/**"
       - "packages/**/test/**"
       - "packages/zone.js/*"
+      - "packages/zone.js/dist/**"
       - "packages/zone.js/doc/**"
       - "packages/zone.js/example/**"
       - "packages/zone.js/scripts/**"

.github/workflows/lock-closed.yml

@@ -10,6 +10,6 @@ jobs:
     if: github.repository == 'angular/angular'
     runs-on: ubuntu-latest
     steps:
-      - uses: angular/dev-infra/github-actions/lock-closed@66462f6
+      - uses: angular/dev-infra/github-actions/lock-closed@414834b2b24dd2df37c6ed00808387ee6fd91b66
         with:
           lock-bot-key: ${{ secrets.LOCK_BOT_PRIVATE_KEY }}

.gitignore

@@ -40,6 +40,9 @@ yarn-error.log
 # User specific bazel settings
 .bazelrc.user
 
+# User specific ng-dev settings
+.ng-dev.user*
+
 .notes.md
 baseline.json
 

.yarn/releases/yarn-1.22.5.js

@@ -44654,7 +44654,7 @@ const FOLDERS_IGNORE = [
 const DEFAULT_IGNORE = (0, (_filter || _load_filter()).ignoreLinesToRegex)([...FOLDERS_IGNORE,
 
 // ignore cruft
-'yarn.lock', '.lock-wscript', '.wafpickle-{0..9}', '*.swp', '._*', 'npm-debug.log', 'yarn-error.log', '.npmrc', '.yarnrc', '.npmignore', '.gitignore', '.DS_Store']);
+'yarn.lock', '.lock-wscript', '.wafpickle-{0..9}', '*.swp', '._*', 'npm-debug.log', 'yarn-error.log', '.npmrc', '.yarnrc', '.yarnrc.yml', '.npmignore', '.gitignore', '.DS_Store']);
 
 const NEVER_IGNORE = (0, (_filter || _load_filter()).ignoreLinesToRegex)([
 // never ignore these files
@@ -44663,6 +44663,7 @@ const NEVER_IGNORE = (0, (_filter || _load_filter()).ignoreLinesToRegex)([
 function packWithIgnoreAndHeaders(cwd, ignoreFunction, { mapHeader } = {}) {
   return tar.pack(cwd, {
     ignore: ignoreFunction,
+    sort: true,
     map: header => {
       const suffix = header.name === '.' ? '' : `/${header.name}`;
       header.name = `package${suffix}`;
@@ -46678,7 +46679,7 @@ function mkdirfix (name, opts, cb) {
 /* 194 */
 /***/ (function(module, exports) {
 
-module.exports = {"name":"yarn","installationMethod":"unknown","version":"1.22.4","license":"BSD-2-Clause","preferGlobal":true,"description":"📦🐈 Fast, reliable, and secure dependency management.","dependencies":{"@zkochan/cmd-shim":"^3.1.0","babel-runtime":"^6.26.0","bytes":"^3.0.0","camelcase":"^4.0.0","chalk":"^2.1.0","cli-table3":"^0.4.0","commander":"^2.9.0","death":"^1.0.0","debug":"^3.0.0","deep-equal":"^1.0.1","detect-indent":"^5.0.0","dnscache":"^1.0.1","glob":"^7.1.1","gunzip-maybe":"^1.4.0","hash-for-dep":"^1.2.3","imports-loader":"^0.8.0","ini":"^1.3.4","inquirer":"^6.2.0","invariant":"^2.2.0","is-builtin-module":"^2.0.0","is-ci":"^1.0.10","is-webpack-bundle":"^1.0.0","js-yaml":"^3.13.1","leven":"^2.0.0","loud-rejection":"^1.2.0","micromatch":"^2.3.11","mkdirp":"^0.5.1","node-emoji":"^1.6.1","normalize-url":"^2.0.0","npm-logical-tree":"^1.2.1","object-path":"^0.11.2","proper-lockfile":"^2.0.0","puka":"^1.0.0","read":"^1.0.7","request":"^2.87.0","request-capture-har":"^1.2.2","rimraf":"^2.5.0","semver":"^5.1.0","ssri":"^5.3.0","strip-ansi":"^4.0.0","strip-bom":"^3.0.0","tar-fs":"^1.16.0","tar-stream":"^1.6.1","uuid":"^3.0.1","v8-compile-cache":"^2.0.0","validate-npm-package-license":"^3.0.4","yn":"^2.0.0"},"devDependencies":{"babel-core":"^6.26.0","babel-eslint":"^7.2.3","babel-loader":"^6.2.5","babel-plugin-array-includes":"^2.0.3","babel-plugin-inline-import":"^3.0.0","babel-plugin-transform-builtin-extend":"^1.1.2","babel-plugin-transform-inline-imports-commonjs":"^1.0.0","babel-plugin-transform-runtime":"^6.4.3","babel-preset-env":"^1.6.0","babel-preset-flow":"^6.23.0","babel-preset-stage-0":"^6.0.0","babylon":"^6.5.0","commitizen":"^2.9.6","cz-conventional-changelog":"^2.0.0","eslint":"^4.3.0","eslint-config-fb-strict":"^22.0.0","eslint-plugin-babel":"^5.0.0","eslint-plugin-flowtype":"^2.35.0","eslint-plugin-jasmine":"^2.6.2","eslint-plugin-jest":"^21.0.0","eslint-plugin-jsx-a11y":"^6.0.2","eslint-plugin-prefer-object-spread":"^1.2.1","eslint-plugin-prettier":"^2.1.2","eslint-plugin-react":"^7.1.0","eslint-plugin-relay":"^0.0.28","eslint-plugin-yarn-internal":"file:scripts/eslint-rules","execa":"^0.11.0","fancy-log":"^1.3.2","flow-bin":"^0.66.0","git-release-notes":"^3.0.0","gulp":"^4.0.0","gulp-babel":"^7.0.0","gulp-if":"^2.0.1","gulp-newer":"^1.0.0","gulp-plumber":"^1.0.1","gulp-sourcemaps":"^2.2.0","jest":"^22.4.4","jsinspect":"^0.12.6","minimatch":"^3.0.4","mock-stdin":"^0.3.0","prettier":"^1.5.2","string-replace-loader":"^2.1.1","temp":"^0.8.3","webpack":"^2.1.0-beta.25","yargs":"^6.3.0"},"resolutions":{"sshpk":"^1.14.2"},"engines":{"node":">=4.0.0"},"repository":"yarnpkg/yarn","bin":{"yarn":"./bin/yarn.js","yarnpkg":"./bin/yarn.js"},"scripts":{"build":"gulp build","build-bundle":"node ./scripts/build-webpack.js","build-chocolatey":"powershell ./scripts/build-chocolatey.ps1","build-deb":"./scripts/build-deb.sh","build-dist":"bash ./scripts/build-dist.sh","build-win-installer":"scripts\\build-windows-installer.bat","changelog":"git-release-notes $(git describe --tags --abbrev=0 $(git describe --tags --abbrev=0)^)..$(git describe --tags --abbrev=0) scripts/changelog.md","dupe-check":"yarn jsinspect ./src","lint":"eslint . && flow check","pkg-tests":"yarn --cwd packages/pkg-tests jest yarn.test.js","prettier":"eslint src __tests__ --fix","release-branch":"./scripts/release-branch.sh","test":"yarn lint && yarn test-only","test-only":"node --max_old_space_size=4096 node_modules/jest/bin/jest.js --verbose","test-only-debug":"node --inspect-brk --max_old_space_size=4096 node_modules/jest/bin/jest.js --runInBand --verbose","test-coverage":"node --max_old_space_size=4096 node_modules/jest/bin/jest.js --coverage --verbose","watch":"gulp watch","commit":"git-cz"},"jest":{"collectCoverageFrom":["src/**/*.js"],"testEnvironment":"node","modulePathIgnorePatterns":["__tests__/fixtures/","packages/pkg-tests/pkg-tests-fixtures","dist/"],"testPathIgnorePatterns":["__tests__/(fixtures|__mocks__)/","updates/","_(temp|mock|install|init|helpers).js$","packages/pkg-tests"]},"config":{"commitizen":{"path":"./node_modules/cz-conventional-changelog"}}}
+module.exports = {"name":"yarn","installationMethod":"unknown","version":"1.22.5","license":"BSD-2-Clause","preferGlobal":true,"description":"📦🐈 Fast, reliable, and secure dependency management.","dependencies":{"@zkochan/cmd-shim":"^3.1.0","babel-runtime":"^6.26.0","bytes":"^3.0.0","camelcase":"^4.0.0","chalk":"^2.1.0","cli-table3":"^0.4.0","commander":"^2.9.0","death":"^1.0.0","debug":"^3.0.0","deep-equal":"^1.0.1","detect-indent":"^5.0.0","dnscache":"^1.0.1","glob":"^7.1.1","gunzip-maybe":"^1.4.0","hash-for-dep":"^1.2.3","imports-loader":"^0.8.0","ini":"^1.3.4","inquirer":"^6.2.0","invariant":"^2.2.0","is-builtin-module":"^2.0.0","is-ci":"^1.0.10","is-webpack-bundle":"^1.0.0","js-yaml":"^3.13.1","leven":"^2.0.0","loud-rejection":"^1.2.0","micromatch":"^2.3.11","mkdirp":"^0.5.1","node-emoji":"^1.6.1","normalize-url":"^2.0.0","npm-logical-tree":"^1.2.1","object-path":"^0.11.2","proper-lockfile":"^2.0.0","puka":"^1.0.0","read":"^1.0.7","request":"^2.87.0","request-capture-har":"^1.2.2","rimraf":"^2.5.0","semver":"^5.1.0","ssri":"^5.3.0","strip-ansi":"^4.0.0","strip-bom":"^3.0.0","tar-fs":"^1.16.0","tar-stream":"^1.6.1","uuid":"^3.0.1","v8-compile-cache":"^2.0.0","validate-npm-package-license":"^3.0.4","yn":"^2.0.0"},"devDependencies":{"babel-core":"^6.26.0","babel-eslint":"^7.2.3","babel-loader":"^6.2.5","babel-plugin-array-includes":"^2.0.3","babel-plugin-inline-import":"^3.0.0","babel-plugin-transform-builtin-extend":"^1.1.2","babel-plugin-transform-inline-imports-commonjs":"^1.0.0","babel-plugin-transform-runtime":"^6.4.3","babel-preset-env":"^1.6.0","babel-preset-flow":"^6.23.0","babel-preset-stage-0":"^6.0.0","babylon":"^6.5.0","commitizen":"^2.9.6","cz-conventional-changelog":"^2.0.0","eslint":"^4.3.0","eslint-config-fb-strict":"^22.0.0","eslint-plugin-babel":"^5.0.0","eslint-plugin-flowtype":"^2.35.0","eslint-plugin-jasmine":"^2.6.2","eslint-plugin-jest":"^21.0.0","eslint-plugin-jsx-a11y":"^6.0.2","eslint-plugin-prefer-object-spread":"^1.2.1","eslint-plugin-prettier":"^2.1.2","eslint-plugin-react":"^7.1.0","eslint-plugin-relay":"^0.0.28","eslint-plugin-yarn-internal":"file:scripts/eslint-rules","execa":"^0.11.0","fancy-log":"^1.3.2","flow-bin":"^0.66.0","git-release-notes":"^3.0.0","gulp":"^4.0.0","gulp-babel":"^7.0.0","gulp-if":"^2.0.1","gulp-newer":"^1.0.0","gulp-plumber":"^1.0.1","gulp-sourcemaps":"^2.2.0","jest":"^22.4.4","jsinspect":"^0.12.6","minimatch":"^3.0.4","mock-stdin":"^0.3.0","prettier":"^1.5.2","string-replace-loader":"^2.1.1","temp":"^0.8.3","webpack":"^2.1.0-beta.25","yargs":"^6.3.0"},"resolutions":{"sshpk":"^1.14.2"},"engines":{"node":">=4.0.0"},"repository":"yarnpkg/yarn","bin":{"yarn":"./bin/yarn.js","yarnpkg":"./bin/yarn.js"},"scripts":{"build":"gulp build","build-bundle":"node ./scripts/build-webpack.js","build-chocolatey":"powershell ./scripts/build-chocolatey.ps1","build-deb":"./scripts/build-deb.sh","build-dist":"bash ./scripts/build-dist.sh","build-win-installer":"scripts\\build-windows-installer.bat","changelog":"git-release-notes $(git describe --tags --abbrev=0 $(git describe --tags --abbrev=0)^)..$(git describe --tags --abbrev=0) scripts/changelog.md","dupe-check":"yarn jsinspect ./src","lint":"eslint . && flow check","pkg-tests":"yarn --cwd packages/pkg-tests jest yarn.test.js","prettier":"eslint src __tests__ --fix","release-branch":"./scripts/release-branch.sh","test":"yarn lint && yarn test-only","test-only":"node --max_old_space_size=4096 node_modules/jest/bin/jest.js --verbose","test-only-debug":"node --inspect-brk --max_old_space_size=4096 node_modules/jest/bin/jest.js --runInBand --verbose","test-coverage":"node --max_old_space_size=4096 node_modules/jest/bin/jest.js --coverage --verbose","watch":"gulp watch","commit":"git-cz"},"jest":{"collectCoverageFrom":["src/**/*.js"],"testEnvironment":"node","modulePathIgnorePatterns":["__tests__/fixtures/","packages/pkg-tests/pkg-tests-fixtures","dist/"],"testPathIgnorePatterns":["__tests__/(fixtures|__mocks__)/","updates/","_(temp|mock|install|init|helpers).js$","packages/pkg-tests"]},"config":{"commitizen":{"path":"./node_modules/cz-conventional-changelog"}}}
 
 /***/ }),
 /* 195 */
@@ -98338,7 +98339,7 @@ var _buildSubCommands = (0, (_buildSubCommands2 || _load_buildSubCommands()).def
 
       const bundle = yield fetchBundle(config, bundleUrl);
 
-      const yarnPath = path.resolve(config.lockfileFolder, `.yarn/releases/yarn-${bundleVersion}.js`);
+      const yarnPath = path.resolve(config.lockfileFolder, `.yarn/releases/yarn-${bundleVersion}.cjs`);
       reporter.log(`Saving it into ${chalk.magenta(yarnPath)}...`);
       yield (_fs || _load_fs()).mkdirp(path.dirname(yarnPath));
       yield (_fs || _load_fs()).writeFile(yarnPath, bundle);
@@ -100190,7 +100191,7 @@ let main = exports.main = (() => {
 
     const config = new (_config || _load_config()).default(reporter);
     const outputWrapperEnabled = (0, (_conversion || _load_conversion()).boolifyWithDefault)(process.env.YARN_WRAP_OUTPUT, true);
-    const shouldWrapOutput = outputWrapperEnabled && !(_commander || _load_commander()).default.json && command.hasWrapper((_commander || _load_commander()).default, (_commander || _load_commander()).default.args);
+    const shouldWrapOutput = outputWrapperEnabled && !(_commander || _load_commander()).default.json && command.hasWrapper((_commander || _load_commander()).default, (_commander || _load_commander()).default.args) && !(commandName === 'init' && (_commander || _load_commander()).default[`2`]);
 
     if (shouldWrapOutput) {
       reporter.header(commandName, { name: 'yarn', version: (_yarnVersion || _load_yarnVersion()).version });
@@ -100604,7 +100605,7 @@ let start = (() => {
       });
 
       try {
-        if (yarnPath.endsWith(`.js`)) {
+        if (/\.[cm]?js$/.test(yarnPath)) {
           exitCode = yield (0, (_child || _load_child()).spawnp)(process.execPath, [yarnPath, ...argv], opts);
         } else {
           exitCode = yield (0, (_child || _load_child()).spawnp)(yarnPath, argv, opts);

.yarnrc

@@ -2,4 +2,4 @@
 # yarn lockfile v1
 
 
-yarn-path ".yarn/releases/yarn-1.22.4.js"
+yarn-path ".yarn/releases/yarn-1.22.5.js"

BUILD.bazel

@@ -34,7 +34,7 @@ filegroup(
 filegroup(
     name = "angularjs_scripts",
     srcs = [
-        # We also declare the unminfied AngularJS files since these can be used for
+        # We also declare the unminified AngularJS files since these can be used for
         # local debugging (e.g. see: packages/upgrade/test/common/test_helpers.ts)
         "@npm//:node_modules/angular/angular.js",
         "@npm//:node_modules/angular/angular.min.js",

CHANGELOG.md

@@ -1,3 +1,142 @@
+<a name="11.0.0-next.3"></a>
+# 11.0.0-next.3 (2020-09-23)
+
+
+### Bug Fixes
+
+* **common:** add `params` and `reportProgress` options to `HttpClient.put()` overload ([#37873](https://github.com/angular/angular/issues/37873)) ([dd8d8c8](https://github.com/angular/angular/commit/dd8d8c8)), closes [#23600](https://github.com/angular/angular/issues/23600)
+* **compiler-cli:** generate `let` statements in ES2015+ mode ([#38775](https://github.com/angular/angular/issues/38775)) ([123bff7](https://github.com/angular/angular/commit/123bff7))
+* **core:** ensure TestBed is not instantiated before override provider ([#38717](https://github.com/angular/angular/issues/38717)) ([c8f056b](https://github.com/angular/angular/commit/c8f056b))
+* **forms:** type NG_VALUE_ACCESSOR injection token as array ([#29723](https://github.com/angular/angular/issues/29723)) ([2b1b718](https://github.com/angular/angular/commit/2b1b718)), closes [#29351](https://github.com/angular/angular/issues/29351)
+
+
+### Features
+
+* **common:** Add ISO week-numbering year formats support to formatDate ([#38828](https://github.com/angular/angular/issues/38828)) ([984ed39](https://github.com/angular/angular/commit/984ed39))
+* **compiler:** Parse and recover on incomplete opening HTML tags ([#38681](https://github.com/angular/angular/issues/38681)) ([6ae3b68](https://github.com/angular/angular/commit/6ae3b68)), closes [#38596](https://github.com/angular/angular/issues/38596)
+* **router:** add migration to update calls to navigateByUrl and createUrlTree with invalid parameters ([#38825](https://github.com/angular/angular/issues/38825)) ([7849fdd](https://github.com/angular/angular/commit/7849fdd)), closes [#38227](https://github.com/angular/angular/issues/38227)
+* **service-worker:** add the option to prefer network for navigation requests ([#38565](https://github.com/angular/angular/issues/38565)) ([a206852](https://github.com/angular/angular/commit/a206852)), closes [#38194](https://github.com/angular/angular/issues/38194)
+
+
+### BREAKING CHANGES
+
+* **core:** If you call `TestBed.overrideProvider` after TestBed initialization, provider overrides are not applied. This
+behavior is consistent with other override methods (such as `TestBed.overrideDirective`, etc) but they
+throw an error to indicate that, when the check was missing in the `TestBed.overrideProvider` function.
+Now calling `TestBed.overrideProvider` after TestBed initialization also triggers an
+error, thus there is a chance that some tests (where `TestBed.overrideProvider` is
+called after TestBed initialization) will start to fail and require updates to move `TestBed.overrideProvider` calls
+before TestBed initialization is completed.
+
+
+
+<a name="10.1.3"></a>
+## 10.1.3 (2020-09-23)
+
+
+### Bug Fixes
+
+* **http:** Fix error message when we call jsonp without importing HttpClientJsonpModule ([#38756](https://github.com/angular/angular/issues/38756)) ([3902ec0](https://github.com/angular/angular/commit/3902ec0))
+* **ngcc:** fix compilation of `ChangeDetectorRef` in pipe constructors ([#38892](https://github.com/angular/angular/issues/38892)) ([093c3a1](https://github.com/angular/angular/commit/093c3a1)), closes [#38666](https://github.com/angular/angular/issues/38666) [#38883](https://github.com/angular/angular/issues/38883)
+
+
+### Reverts
+
+* feat(router): better warning message when a router outlet has not been instantiated ([#38920](https://github.com/angular/angular/issues/38920)) ([04d0aa6](https://github.com/angular/angular/commit/04d0aa6))
+
+
+
+<a name="11.0.0-next.2"></a>
+# 11.0.0-next.2 (2020-09-16)
+
+
+### Bug Fixes
+
+* **common:** do not round up fractions of a millisecond in `DatePipe` ([#38009](https://github.com/angular/angular/issues/38009)) ([26f2820](https://github.com/angular/angular/commit/26f2820)), closes [/www.ecma-international.org/ecma-262/5.1/#sec-15](https://github.com//www.ecma-international.org/ecma-262/5.1//issues/sec-15) [#37989](https://github.com/angular/angular/issues/37989)
+* **common:** mark locale data arrays as readonly ([#30397](https://github.com/angular/angular/issues/30397)) ([6acea54](https://github.com/angular/angular/commit/6acea54)), closes [#27003](https://github.com/angular/angular/issues/27003)
+* **compiler:** source span for microsyntax text att should be key span ([#38766](https://github.com/angular/angular/issues/38766)) ([8f349b2](https://github.com/angular/angular/commit/8f349b2))
+* **router:** Fix arguments order for call to shouldReuseRoute ([#26949](https://github.com/angular/angular/issues/26949)) ([3817e5f](https://github.com/angular/angular/commit/3817e5f)), closes [#16192](https://github.com/angular/angular/issues/16192) [#16192](https://github.com/angular/angular/issues/16192)
+
+
+### Features
+
+* **compiler-cli:** `TemplateTypeChecker` operation to get `Symbol` from a template node ([#38618](https://github.com/angular/angular/issues/38618)) ([c4556db](https://github.com/angular/angular/commit/c4556db))
+* **compiler-cli:** Add ability to get `Symbol` of `Template`s and `Element`s in component template ([#38618](https://github.com/angular/angular/issues/38618)) ([cf2e8b9](https://github.com/angular/angular/commit/cf2e8b9))
+* **compiler-cli:** Add ability to get `Symbol` of AST expression in component template ([#38618](https://github.com/angular/angular/issues/38618)) ([f56ece4](https://github.com/angular/angular/commit/f56ece4))
+* **compiler-cli:** add ability to get symbol of reference or variable ([#38618](https://github.com/angular/angular/issues/38618)) ([19598b4](https://github.com/angular/angular/commit/19598b4))
+* **compiler-cli:** define interfaces to be used for TemplateTypeChecker ([#38618](https://github.com/angular/angular/issues/38618)) ([9e77bd3](https://github.com/angular/angular/commit/9e77bd3))
+
+
+### Performance Improvements
+
+* **compiler-cli:** only emit directive/pipe references that are used ([#38539](https://github.com/angular/angular/issues/38539)) ([077f516](https://github.com/angular/angular/commit/077f516))
+* **compiler-cli:** optimize computation of type-check scope information ([#38539](https://github.com/angular/angular/issues/38539)) ([297c060](https://github.com/angular/angular/commit/297c060))
+* **router:** use `ngDevMode` to tree-shake error messages in router ([#38674](https://github.com/angular/angular/issues/38674)) ([db21c4f](https://github.com/angular/angular/commit/db21c4f))
+
+
+### BREAKING CHANGES
+
+* **router:** This change corrects the argument order when calling
+RouteReuseStrategy#shouldReuseRoute. Previously, when evaluating child
+routes, they would be called with the future and current arguments would
+be swapped. If your RouteReuseStrategy relies specifically on only the future
+or current snapshot state, you may need to update the shouldReuseRoute
+implementation's use of "future" and "current" ActivateRouteSnapshots.
+* **common:** The locale data API has been marked as returning readonly arrays, rather
+than mutable arrays, since these arrays are shared across calls to the
+API. If you were mutating them (e.g. calling `sort()`, `push()`, `splice()`, etc)
+then your code will not longer compile. If you need to mutate the array, you
+should now take a copy (e.g. by calling `slice()`) and mutate the copy.
+* **common:** When passing a date-time formatted string to the `DatePipe` in a format that contains
+fractions of a millisecond, the milliseconds will now always be rounded down rather than
+to the nearest millisecond.
+
+Most applications will not be affected by this change. If this is not the desired behaviour
+then consider pre-processing the string to round the millisecond part before passing
+it to the `DatePipe`.
+
+
+
+<a name="10.1.2"></a>
+## 10.1.2 (2020-09-16)
+
+
+### Bug Fixes
+
+* **compiler:** detect pipes in ICUs in template binder ([#38810](https://github.com/angular/angular/issues/38810)) ([ec2dbe7](https://github.com/angular/angular/commit/ec2dbe7)), closes [#38539](https://github.com/angular/angular/issues/38539) [#38539](https://github.com/angular/angular/issues/38539) [#38539](https://github.com/angular/angular/issues/38539)
+* **core:** clear the `RefreshTransplantedView` when detached ([#38768](https://github.com/angular/angular/issues/38768)) ([edb7f90](https://github.com/angular/angular/commit/edb7f90)), closes [#38619](https://github.com/angular/angular/issues/38619)
+* **localize:** ensure that `formatOptions` is optional ([#38787](https://github.com/angular/angular/issues/38787)) ([a47383d](https://github.com/angular/angular/commit/a47383d))
+* **router:** Ensure routes are processed in priority order and only if needed ([#38780](https://github.com/angular/angular/issues/38780)) ([9c51ba3](https://github.com/angular/angular/commit/9c51ba3)), closes [#38691](https://github.com/angular/angular/issues/38691)
+* **upgrade:** add try/catch when downgrading injectables ([#38671](https://github.com/angular/angular/issues/38671)) ([5de2ac3](https://github.com/angular/angular/commit/5de2ac3)), closes [#37579](https://github.com/angular/angular/issues/37579)
+
+
+### Performance Improvements
+
+* **compiler-cli:** only emit directive/pipe references that are used ([#38843](https://github.com/angular/angular/issues/38843)) ([5658405](https://github.com/angular/angular/commit/5658405))
+* **compiler-cli:** optimize computation of type-check scope information ([#38843](https://github.com/angular/angular/issues/38843)) ([ebede67](https://github.com/angular/angular/commit/ebede67))
+* **ngcc:** introduce cache for sharing data across entry-points ([#38840](https://github.com/angular/angular/issues/38840)) ([58411e7](https://github.com/angular/angular/commit/58411e7))
+* **ngcc:** reduce maximum worker count ([#38840](https://github.com/angular/angular/issues/38840)) ([ea36466](https://github.com/angular/angular/commit/ea36466))
+
+
+
+<a name="11.0.0-next.1"></a>
+# 11.0.0-next.1 (2020-09-09)
+
+
+### Bug Fixes
+
+* **compiler-cli:** compute source-mappings for localized strings ([#38645](https://github.com/angular/angular/issues/38645)) ([7e0b3fd](https://github.com/angular/angular/commit/7e0b3fd)), closes [#38588](https://github.com/angular/angular/issues/38588)
+* **core:** remove CollectionChangeRecord symbol ([#38668](https://github.com/angular/angular/issues/38668)) ([fdea180](https://github.com/angular/angular/commit/fdea180))
+* **router:** support lazy loading for empty path named outlets ([#38379](https://github.com/angular/angular/issues/38379)) ([926ffcd](https://github.com/angular/angular/commit/926ffcd)), closes [#12842](https://github.com/angular/angular/issues/12842)
+
+
+### BREAKING CHANGES
+
+* **core:** CollectionChangeRecord has been removed, use IterableChangeRecord
+instead
+
+
+
 <a name="10.1.1"></a>
 ## 10.1.1 (2020-09-09)
 
@@ -23,6 +162,31 @@
 
 
 
+<a name="11.0.0-next.0"></a>
+# 11.0.0-next.0 (2020-09-02)
+
+
+### Bug Fixes
+
+* **forms:** ensure to emit `statusChanges` on subsequent value update/validations ([#38354](https://github.com/angular/angular/issues/38354)) ([d9fea85](https://github.com/angular/angular/commit/d9fea85)), closes [#20424](https://github.com/angular/angular/issues/20424) [#14542](https://github.com/angular/angular/issues/14542)
+* **service-worker:** fix condition to check for a cache-busted request ([#36847](https://github.com/angular/angular/issues/36847)) ([5be4edf](https://github.com/angular/angular/commit/5be4edf))
+
+
+### Features
+
+* **service-worker:** add `UnrecoverableStateError` ([#36847](https://github.com/angular/angular/issues/36847)) ([036a2fa](https://github.com/angular/angular/commit/036a2fa)), closes [#36539](https://github.com/angular/angular/issues/36539)
+
+
+### BREAKING CHANGES
+
+* **forms:** Previously if FormControl, FormGroup and FormArray class instances had async validators
+defined at initialization time, the status change event was not emitted once async validator
+completed. After this change the status event is emitted into the `statusChanges` observable.
+If your code relies on the old behavior, you can filter/ignore this additional status change
+event.
+
+
+
 <a name="10.1.0"></a>
 # 10.1.0 (2020-09-02)
 

aio/content/examples/bootstrapping/src/app/app.module.ts

@@ -21,11 +21,13 @@ import { ItemDirective } from './item.directive';
     ItemDirective
   ],
   // #enddocregion declarations
+  // #docregion imports
   imports: [
     BrowserModule,
     FormsModule,
     HttpClientModule
   ],
+  // #enddocregion imports
   providers: [],
   bootstrap: [AppComponent]
 })

aio/content/examples/comparing-observables/e2e/src/app.e2e-spec.ts

@@ -0,0 +1,9 @@
+/*
+ * This example project is special in that it is not a cli app. To run tests appropriate for this
+ * project, the test command is overwritten in `aio/content/examples/observables/example-config.json`.
+ *
+ * This is an empty placeholder file to ensure that `aio/tools/examples/run-example-e2e.js` runs
+ * tests for this project.
+ *
+ * TODO: Fix our infrastructure/tooling, so that this hack is not necessary.
+ */

aio/content/examples/comparing-observables/example-config.json

@@ -0,0 +1,12 @@
+{
+  "tests": [
+    {
+      "cmd": "yarn",
+      "args": ["tsc", "--project", "tsconfig.spec.json", "--module", "commonjs"]
+    },
+    {
+      "cmd": "yarn",
+      "args": ["jasmine", "out-tsc/**/*.spec.js"]
+    }
+  ]
+}

aio/content/examples/comparing-observables/src/observables.spec.ts

@@ -0,0 +1,26 @@
+import { docRegionChain, docRegionObservable, docRegionUnsubscribe } from './observables';
+
+describe('observables', () => {
+  it('should print 2', (doneFn: DoneFn) => {
+    const consoleLogSpy = spyOn(console, 'log');
+    const observable = docRegionObservable(console);
+    observable.subscribe(() => {
+      expect(consoleLogSpy).toHaveBeenCalledTimes(1);
+      expect(consoleLogSpy).toHaveBeenCalledWith(2);
+      doneFn();
+    });
+  });
+
+  it('should close the subscription', () => {
+    const subscription = docRegionUnsubscribe();
+    expect(subscription.closed).toBeTruthy();
+  });
+
+  it('should chain an observable', (doneFn: DoneFn) => {
+    const observable = docRegionChain();
+    observable.subscribe(value => {
+      expect(value).toBe(4);
+      doneFn();
+    });
+  });
+});

aio/content/examples/comparing-observables/src/observables.ts

@@ -1,40 +1,72 @@
-import { map } from 'rxjs/operators';
+// #docplaster
+
 import { Observable } from 'rxjs';
+import { map } from 'rxjs/operators';
 
-// #docregion observable
+export function docRegionObservable(console: Console) {
+  // #docregion observable
 
-// declare a publishing operation
-const observable = new Observable<number>(observer => {
-  // Subscriber fn...
-});
+  // declare a publishing operation
+  const observable = new Observable<number>(observer => {
+    // Subscriber fn...
+    // #enddocregion observable
+    // The below code is used for unit testing only
+    observer.next(2);
+    // #docregion observable
+  });
 
-// initiate execution
-observable.subscribe(() => {
-  // observer handles notifications
-});
+  // initiate execution
+  observable.subscribe(value => {
+    // observer handles notifications
+    // #enddocregion observable
+    // The below code is used for unit testing only
+    console.log(value);
+    // #docregion observable
+  });
 
-// #enddocregion observable
+  // #enddocregion observable
+  return observable;
+}
 
-// #docregion unsubscribe
+export function docRegionUnsubscribe() {
+  const observable = new Observable<number>(() => {
+    // Subscriber fn...
+  });
+  // #docregion unsubscribe
 
-const subscription = observable.subscribe(() => {
-  // observer handles notifications
-});
+  const subscription = observable.subscribe(() => {
+    // observer handles notifications
+  });
 
-subscription.unsubscribe();
+  subscription.unsubscribe();
 
-// #enddocregion unsubscribe
+  // #enddocregion unsubscribe
+  return subscription;
+}
 
-// #docregion error
+export function docRegionError() {
+  const observable = new Observable<number>(() => {
+    // Subscriber fn...
+  });
 
-observable.subscribe(() => {
-  throw Error('my error');
-});
+  // #docregion error
+  observable.subscribe(() => {
+    throw new Error('my error');
+  });
+  // #enddocregion error
+}
 
-// #enddocregion error
+export function docRegionChain() {
+  let observable = new Observable<number>(observer => {
+    // Subscriber fn...
+    observer.next(2);
+  });
 
-// #docregion chain
+  observable =
+  // #docregion chain
 
-observable.pipe(map(v => 2 * v));
+  observable.pipe(map(v => 2 * v));
 
-// #enddocregion chain
+  // #enddocregion chain
+  return observable;
+}

aio/content/examples/comparing-observables/src/promises.spec.ts

@@ -0,0 +1,23 @@
+import { docRegionError, docRegionPromise } from './promises';
+
+describe('promises', () => {
+  it('should print 2', (doneFn: DoneFn) => {
+    const consoleLogSpy = spyOn(console, 'log');
+    const pr = docRegionPromise(console, 2);
+    pr.then((value) => {
+      expect(consoleLogSpy).toHaveBeenCalledTimes(1);
+      expect(consoleLogSpy).toHaveBeenCalledWith(2);
+      expect(value).toBe(4);
+      doneFn();
+    });
+  });
+
+  it('should throw an error', (doneFn: DoneFn) => {
+    const promise = docRegionError();
+    promise
+      .then(() => {
+        throw new Error('Promise should be rejected.');
+      },
+        () => doneFn());
+  });
+});

aio/content/examples/comparing-observables/src/promises.ts

@@ -1,25 +1,44 @@
-// #docregion promise
-// initiate execution
-const promise = new Promise<number>((resolve, reject) => {
-  // Executer fn...
-});
+// #docplaster
 
-promise.then(value => {
-  // handle result here
-});
+export function docRegionPromise(console: Console, inputValue: number) {
+  // #docregion promise
+  // initiate execution
+  let promise = new Promise<number>((resolve, reject) => {
+    // Executer fn...
+    // #enddocregion promise
+    // The below is used in the unit tests.
+    resolve(inputValue);
+    // #docregion promise
+  });
+  // #enddocregion promise
+  promise =
+  // #docregion promise
+  promise.then(value => {
+    // handle result here
+    // #enddocregion promise
+    // The below is used in the unit tests.
+    console.log(value);
+    return value;
+    // #docregion promise
+  });
+  // #enddocregion promise
+  promise =
+  // #docregion chain
+  promise.then(v => 2 * v);
+  // #enddocregion chain
 
-// #enddocregion promise
+  return promise;
+}
 
-// #docregion chain
+export function docRegionError() {
+  let promise = Promise.resolve();
+  promise =
+  // #docregion error
 
-promise.then(v => 2 * v);
+  promise.then(() => {
+    throw new Error('my error');
+  });
 
-// #enddocregion chain
-
-// #docregion error
-
-promise.then(() => {
-  throw Error('my error');
-});
-
-// #enddocregion error
+  // #enddocregion error
+  return promise;
+}

aio/content/examples/observables-in-angular/src/main.ts

@@ -1,3 +1,4 @@
+// TODO: Add unit tests for this file.
 // tslint:disable: no-output-native
 // #docregion
 import { Component, Output, OnInit, EventEmitter, NgModule } from '@angular/core';

aio/content/examples/observables/example-config.json

@@ -2,7 +2,11 @@
   "tests": [
     {
       "cmd": "yarn",
-      "args": [ "tsc", "--project", "./tsconfig.app.json" ]
+      "args": ["tsc", "--project", "tsconfig.spec.json", "--module", "commonjs"]
+    },
+    {
+      "cmd": "yarn",
+      "args": ["jasmine", "out-tsc/**/*.spec.js"]
     }
   ]
 }

aio/content/examples/observables/src/creating.spec.ts

@@ -0,0 +1,55 @@
+import { docRegionFromEvent, docRegionSubscriber } from './creating';
+
+describe('observables', () => {
+  it('should create an observable using the constructor', () => {
+    const console = {log: jasmine.createSpy('log')};
+    docRegionSubscriber(console);
+    expect(console.log).toHaveBeenCalledTimes(4);
+    expect(console.log.calls.allArgs()).toEqual([
+      [1],
+      [2],
+      [3],
+      ['Finished sequence'],
+    ]);
+  });
+
+  it('should listen to input changes', () => {
+    let triggerInputChange;
+    const input = {
+      value: 'Test',
+      addEventListener: jasmine
+        .createSpy('addEvent')
+        .and.callFake((eventName: string, cb: (e) => void) => {
+          if (eventName === 'keydown') {
+            triggerInputChange = cb;
+          }
+        }),
+      removeEventListener: jasmine.createSpy('removeEventListener'),
+    };
+
+    const document = { getElementById: () => input };
+    docRegionFromEvent(document);
+    triggerInputChange({keyCode: 65});
+    expect(input.value).toBe('Test');
+
+    triggerInputChange({keyCode: 27});
+    expect(input.value).toBe('');
+  });
+
+  it('should call removeEventListener when unsubscribing', (doneFn: DoneFn) => {
+    const input = {
+      addEventListener: jasmine.createSpy('addEvent'),
+      removeEventListener: jasmine
+        .createSpy('removeEvent')
+        .and.callFake((eventName: string, cb: (e) => void) => {
+          if (eventName === 'keydown') {
+            doneFn();
+          }
+        })
+    };
+
+    const document = { getElementById: () => input };
+    const subscription = docRegionFromEvent(document);
+    subscription.unsubscribe();
+  });
+});

aio/content/examples/observables/src/creating.ts

@@ -1,38 +1,39 @@
+// #docplaster
 
 import { Observable } from 'rxjs';
 
-// #docregion subscriber
+export function docRegionSubscriber(console) {
+  // #docregion subscriber
+  // This function runs when subscribe() is called
+  function sequenceSubscriber(observer) {
+    // synchronously deliver 1, 2, and 3, then complete
+    observer.next(1);
+    observer.next(2);
+    observer.next(3);
+    observer.complete();
 
-// This function runs when subscribe() is called
-function sequenceSubscriber(observer) {
-  // synchronously deliver 1, 2, and 3, then complete
-  observer.next(1);
-  observer.next(2);
-  observer.next(3);
-  observer.complete();
+    // unsubscribe function doesn't need to do anything in this
+    // because values are delivered synchronously
+    return {unsubscribe() {}};
+  }
 
-  // unsubscribe function doesn't need to do anything in this
-  // because values are delivered synchronously
-  return {unsubscribe() {}};
+  // Create a new Observable that will deliver the above sequence
+  const sequence = new Observable(sequenceSubscriber);
+
+  // execute the Observable and print the result of each notification
+  sequence.subscribe({
+    next(num) { console.log(num); },
+    complete() { console.log('Finished sequence'); }
+  });
+
+  // Logs:
+  // 1
+  // 2
+  // 3
+  // Finished sequence
+  // #enddocregion subscriber
 }
 
-// Create a new Observable that will deliver the above sequence
-const sequence = new Observable(sequenceSubscriber);
-
-// execute the Observable and print the result of each notification
-sequence.subscribe({
-  next(num) { console.log(num); },
-  complete() { console.log('Finished sequence'); }
-});
-
-// Logs:
-// 1
-// 2
-// 3
-// Finished sequence
-
-// #enddocregion subscriber
-
 // #docregion fromevent
 
 function fromEvent(target, eventName) {
@@ -51,16 +52,18 @@ function fromEvent(target, eventName) {
 
 // #enddocregion fromevent
 
-// #docregion fromevent_use
+export function docRegionFromEvent(document) {
+  // #docregion fromevent_use
 
-const ESC_KEY = 27;
-const nameInput = document.getElementById('name') as HTMLInputElement;
+  const ESC_KEY = 27;
+  const nameInput = document.getElementById('name') as HTMLInputElement;
 
-const subscription = fromEvent(nameInput, 'keydown')
-  .subscribe((e: KeyboardEvent) => {
+  const subscription = fromEvent(nameInput, 'keydown').subscribe((e: KeyboardEvent) => {
     if (e.keyCode === ESC_KEY) {
       nameInput.value = '';
     }
   });
+  // #enddocregion fromevent_use
+  return subscription;
+}
 
-// #enddocregion fromevent_use

aio/content/examples/observables/src/geolocation.ts

@@ -1,5 +1,5 @@
+// TODO: Add unit tests for this file.
 import { Observable } from 'rxjs';
-
 // #docregion
 
 // Create an Observable that will start listening to geolocation updates

aio/content/examples/observables/src/multicasting.spec.ts

@@ -0,0 +1,48 @@
+import { docRegionDelaySequence, docRegionMulticastSequence } from './multicasting';
+
+describe('multicasting', () => {
+  let console;
+  beforeEach(() => {
+    jasmine.clock().install();
+    console = {log: jasmine.createSpy('log')};
+  });
+
+  afterEach(() => {
+    jasmine.clock().uninstall();
+  });
+
+  it('should create an observable and emit in sequence', () => {
+    docRegionDelaySequence(console);
+    jasmine.clock().tick(10000);
+    expect(console.log).toHaveBeenCalledTimes(12);
+    expect(console.log.calls.allArgs()).toEqual([
+      [1],
+      ['1st subscribe: 1'],
+      ['2nd subscribe: 1'],
+      [2],
+      ['1st subscribe: 2'],
+      ['2nd subscribe: 2'],
+      [3],
+      ['Finished sequence'],
+      ['1st subscribe: 3'],
+      ['1st sequence finished.'],
+      ['2nd subscribe: 3'],
+      ['2nd sequence finished.']
+    ]);
+  });
+
+  it('should create an observable and multicast the emissions', () => {
+    docRegionMulticastSequence(console);
+    jasmine.clock().tick(10000);
+    expect(console.log).toHaveBeenCalledTimes(7);
+    expect(console.log.calls.allArgs()).toEqual([
+      ['1st subscribe: 1'],
+      ['1st subscribe: 2'],
+      ['2nd subscribe: 2'],
+      ['1st subscribe: 3'],
+      ['2nd subscribe: 3'],
+      ['1st sequence finished.'],
+      ['2nd sequence finished.']
+    ]);
+  });
+});

aio/content/examples/observables/src/multicasting.ts

@@ -1,155 +1,160 @@
+// #docplaster
 
 import { Observable } from 'rxjs';
 
-// #docregion delay_sequence
+export function docRegionDelaySequence(console) {
+  // #docregion delay_sequence
+  function sequenceSubscriber(observer) {
+    const seq = [1, 2, 3];
+    let timeoutId;
 
-function sequenceSubscriber(observer) {
-  const seq = [1, 2, 3];
-  let timeoutId;
+    // Will run through an array of numbers, emitting one value
+    // per second until it gets to the end of the array.
+    function doInSequence(arr, idx) {
+      timeoutId = setTimeout(() => {
+        observer.next(arr[idx]);
+        if (idx === arr.length - 1) {
+          observer.complete();
+        } else {
+          doInSequence(arr, ++idx);
+        }
+      }, 1000);
+    }
 
-  // Will run through an array of numbers, emitting one value
+    doInSequence(seq, 0);
+
+    // Unsubscribe should clear the timeout to stop execution
+    return {
+      unsubscribe() {
+        clearTimeout(timeoutId);
+      }
+    };
+  }
+
+  // Create a new Observable that will deliver the above sequence
+  const sequence = new Observable(sequenceSubscriber);
+
+  sequence.subscribe({
+    next(num) { console.log(num); },
+    complete() { console.log('Finished sequence'); }
+  });
+
+  // Logs:
+  // (at 1 second): 1
+  // (at 2 seconds): 2
+  // (at 3 seconds): 3
+  // (at 3 seconds): Finished sequence
+
+  // #enddocregion delay_sequence
+
+  // #docregion subscribe_twice
+
+  // Subscribe starts the clock, and will emit after 1 second
+  sequence.subscribe({
+    next(num) { console.log('1st subscribe: ' + num); },
+    complete() { console.log('1st sequence finished.'); }
+  });
+
+  // After 1/2 second, subscribe again.
+  setTimeout(() => {
+    sequence.subscribe({
+      next(num) { console.log('2nd subscribe: ' + num); },
+      complete() { console.log('2nd sequence finished.'); }
+    });
+  }, 500);
+
+  // Logs:
+  // (at 1 second): 1st subscribe: 1
+  // (at 1.5 seconds): 2nd subscribe: 1
+  // (at 2 seconds): 1st subscribe: 2
+  // (at 2.5 seconds): 2nd subscribe: 2
+  // (at 3 seconds): 1st subscribe: 3
+  // (at 3 seconds): 1st sequence finished
+  // (at 3.5 seconds): 2nd subscribe: 3
+  // (at 3.5 seconds): 2nd sequence finished
+
+  // #enddocregion subscribe_twice
+}
+
+export function docRegionMulticastSequence(console) {
+  // #docregion multicast_sequence
+  function multicastSequenceSubscriber() {
+    const seq = [1, 2, 3];
+    // Keep track of each observer (one for every active subscription)
+    const observers = [];
+    // Still a single timeoutId because there will only ever be one
+    // set of values being generated, multicasted to each subscriber
+    let timeoutId;
+
+    // Return the subscriber function (runs when subscribe()
+    // function is invoked)
+    return observer => {
+      observers.push(observer);
+      // When this is the first subscription, start the sequence
+      if (observers.length === 1) {
+        timeoutId = doSequence({
+          next(val) {
+            // Iterate through observers and notify all subscriptions
+            observers.forEach(obs => obs.next(val));
+          },
+          complete() {
+            // Notify all complete callbacks
+            observers.slice(0).forEach(obs => obs.complete());
+          }
+        }, seq, 0);
+      }
+
+      return {
+        unsubscribe() {
+          // Remove from the observers array so it's no longer notified
+          observers.splice(observers.indexOf(observer), 1);
+          // If there's no more listeners, do cleanup
+          if (observers.length === 0) {
+            clearTimeout(timeoutId);
+          }
+        }
+      };
+    };
+  }
+
+  // Run through an array of numbers, emitting one value
   // per second until it gets to the end of the array.
-  function doInSequence(arr, idx) {
-    timeoutId = setTimeout(() => {
+  function doSequence(observer, arr, idx) {
+    return setTimeout(() => {
       observer.next(arr[idx]);
       if (idx === arr.length - 1) {
         observer.complete();
       } else {
-        doInSequence(arr, ++idx);
+        doSequence(observer, arr, ++idx);
       }
     }, 1000);
   }
 
-  doInSequence(seq, 0);
+  // Create a new Observable that will deliver the above sequence
+  const multicastSequence = new Observable(multicastSequenceSubscriber());
 
-  // Unsubscribe should clear the timeout to stop execution
-  return {unsubscribe() {
-    clearTimeout(timeoutId);
-  }};
-}
-
-// Create a new Observable that will deliver the above sequence
-const sequence = new Observable(sequenceSubscriber);
-
-sequence.subscribe({
-  next(num) { console.log(num); },
-  complete() { console.log('Finished sequence'); }
-});
-
-// Logs:
-// (at 1 second): 1
-// (at 2 seconds): 2
-// (at 3 seconds): 3
-// (at 3 seconds): Finished sequence
-
-// #enddocregion delay_sequence
-
-// #docregion subscribe_twice
-
-// Subscribe starts the clock, and will emit after 1 second
-sequence.subscribe({
-  next(num) { console.log('1st subscribe: ' + num); },
-  complete() { console.log('1st sequence finished.'); }
-});
-
-// After 1/2 second, subscribe again.
-setTimeout(() => {
-  sequence.subscribe({
-    next(num) { console.log('2nd subscribe: ' + num); },
-    complete() { console.log('2nd sequence finished.'); }
-  });
-}, 500);
-
-// Logs:
-// (at 1 second): 1st subscribe: 1
-// (at 1.5 seconds): 2nd subscribe: 1
-// (at 2 seconds): 1st subscribe: 2
-// (at 2.5 seconds): 2nd subscribe: 2
-// (at 3 seconds): 1st subscribe: 3
-// (at 3 seconds): 1st sequence finished
-// (at 3.5 seconds): 2nd subscribe: 3
-// (at 3.5 seconds): 2nd sequence finished
-
-// #enddocregion subscribe_twice
-
-// #docregion multicast_sequence
-
-function multicastSequenceSubscriber() {
-  const seq = [1, 2, 3];
-  // Keep track of each observer (one for every active subscription)
-  const observers = [];
-  // Still a single timeoutId because there will only ever be one
-  // set of values being generated, multicasted to each subscriber
-  let timeoutId;
-
-  // Return the subscriber function (runs when subscribe()
-  // function is invoked)
-  return (observer) => {
-    observers.push(observer);
-    // When this is the first subscription, start the sequence
-    if (observers.length === 1) {
-      timeoutId = doSequence({
-        next(val) {
-          // Iterate through observers and notify all subscriptions
-          observers.forEach(obs => obs.next(val));
-        },
-        complete() {
-          // Notify all complete callbacks
-          observers.slice(0).forEach(obs => obs.complete());
-        }
-      }, seq, 0);
-    }
-
-    return {
-      unsubscribe() {
-        // Remove from the observers array so it's no longer notified
-        observers.splice(observers.indexOf(observer), 1);
-        // If there's no more listeners, do cleanup
-        if (observers.length === 0) {
-          clearTimeout(timeoutId);
-        }
-      }
-    };
-  };
-}
-
-// Run through an array of numbers, emitting one value
-// per second until it gets to the end of the array.
-function doSequence(observer, arr, idx) {
-  return setTimeout(() => {
-    observer.next(arr[idx]);
-    if (idx === arr.length - 1) {
-      observer.complete();
-    } else {
-      doSequence(observer, arr, ++idx);
-    }
-  }, 1000);
-}
-
-// Create a new Observable that will deliver the above sequence
-const multicastSequence = new Observable(multicastSequenceSubscriber());
-
-// Subscribe starts the clock, and begins to emit after 1 second
-multicastSequence.subscribe({
-  next(num) { console.log('1st subscribe: ' + num); },
-  complete() { console.log('1st sequence finished.'); }
-});
-
-// After 1 1/2 seconds, subscribe again (should "miss" the first value).
-setTimeout(() => {
+  // Subscribe starts the clock, and begins to emit after 1 second
   multicastSequence.subscribe({
-    next(num) { console.log('2nd subscribe: ' + num); },
-    complete() { console.log('2nd sequence finished.'); }
+    next(num) { console.log('1st subscribe: ' + num); },
+    complete() { console.log('1st sequence finished.'); }
   });
-}, 1500);
 
-// Logs:
-// (at 1 second): 1st subscribe: 1
-// (at 2 seconds): 1st subscribe: 2
-// (at 2 seconds): 2nd subscribe: 2
-// (at 3 seconds): 1st subscribe: 3
-// (at 3 seconds): 1st sequence finished
-// (at 3 seconds): 2nd subscribe: 3
-// (at 3 seconds): 2nd sequence finished
+  // After 1 1/2 seconds, subscribe again (should "miss" the first value).
+  setTimeout(() => {
+    multicastSequence.subscribe({
+      next(num) { console.log('2nd subscribe: ' + num); },
+      complete() { console.log('2nd sequence finished.'); }
+    });
+  }, 1500);
 
-// #enddocregion multicast_sequence
+  // Logs:
+  // (at 1 second): 1st subscribe: 1
+  // (at 2 seconds): 1st subscribe: 2
+  // (at 2 seconds): 2nd subscribe: 2
+  // (at 3 seconds): 1st subscribe: 3
+  // (at 3 seconds): 1st sequence finished
+  // (at 3 seconds): 2nd subscribe: 3
+  // (at 3 seconds): 2nd sequence finished
+
+  // #enddocregion multicast_sequence
+}

aio/content/examples/observables/src/subscribing.spec.ts

@@ -0,0 +1,19 @@
+import { docRegionObserver } from './subscribing';
+
+describe('subscribing', () => {
+  it('should subscribe and emit', () => {
+    const console = {log: jasmine.createSpy('log')};
+    docRegionObserver(console);
+    expect(console.log).toHaveBeenCalledTimes(8);
+    expect(console.log.calls.allArgs()).toEqual([
+      ['Observer got a next value: 1'],
+      ['Observer got a next value: 2'],
+      ['Observer got a next value: 3'],
+      ['Observer got a complete notification'],
+      ['Observer got a next value: 1'],
+      ['Observer got a next value: 2'],
+      ['Observer got a next value: 3'],
+      ['Observer got a complete notification'],
+    ]);
+  });
+});

aio/content/examples/observables/src/subscribing.ts

@@ -1,32 +1,35 @@
+// #docplaster
+import { of } from 'rxjs';
 
-import { Observable, of } from 'rxjs';
+export function docRegionObserver(console) {
+  // #docregion observer
 
-// #docregion observer
+  // Create simple observable that emits three values
+  const myObservable = of(1, 2, 3);
 
-// Create simple observable that emits three values
-const myObservable = of(1, 2, 3);
+  // Create observer object
+  const myObserver = {
+    next: x => console.log('Observer got a next value: ' + x),
+    error: err => console.error('Observer got an error: ' + err),
+    complete: () => console.log('Observer got a complete notification'),
+  };
 
-// Create observer object
-const myObserver = {
-  next: x => console.log('Observer got a next value: ' + x),
-  error: err => console.error('Observer got an error: ' + err),
-  complete: () => console.log('Observer got a complete notification'),
-};
+  // Execute with the observer object
+  myObservable.subscribe(myObserver);
 
-// Execute with the observer object
-myObservable.subscribe(myObserver);
-// Logs:
-// Observer got a next value: 1
-// Observer got a next value: 2
-// Observer got a next value: 3
-// Observer got a complete notification
+  // Logs:
+  // Observer got a next value: 1
+  // Observer got a next value: 2
+  // Observer got a next value: 3
+  // Observer got a complete notification
 
-// #enddocregion observer
+  // #enddocregion observer
 
-// #docregion sub_fn
-myObservable.subscribe(
-  x => console.log('Observer got a next value: ' + x),
-  err => console.error('Observer got an error: ' + err),
-  () => console.log('Observer got a complete notification')
-);
-// #enddocregion sub_fn
+  // #docregion sub_fn
+  myObservable.subscribe(
+    x => console.log('Observer got a next value: ' + x),
+    err => console.error('Observer got an error: ' + err),
+    () => console.log('Observer got a complete notification')
+  );
+  // #enddocregion sub_fn
+}

aio/content/examples/practical-observable-usage/example-config.json

@@ -2,7 +2,11 @@
   "tests": [
     {
       "cmd": "yarn",
-      "args": [ "tsc", "--project", "./tsconfig.app.json" ]
+      "args": ["tsc", "--project", "tsconfig.spec.json", "--module", "commonjs"]
+    },
+    {
+      "cmd": "yarn",
+      "args": ["jasmine", "out-tsc/**/*.spec.js"]
     }
   ]
 }

aio/content/examples/practical-observable-usage/src/backoff.ts

@@ -1,4 +1,4 @@
-
+// TODO: Add unit tests for this file.
 import { pipe, range, timer, zip } from 'rxjs';
 import { ajax } from 'rxjs/ajax';
 import { retryWhen, map, mergeMap } from 'rxjs/operators';

aio/content/examples/practical-observable-usage/src/typeahead.spec.ts

@@ -0,0 +1,72 @@
+import { of } from 'rxjs';
+import { docRegionTypeahead } from './typeahead';
+
+describe('typeahead', () => {
+  let document;
+  let ajax;
+  let triggertInputChange;
+
+  beforeEach(() => {
+    jasmine.clock().install();
+    const input = {
+      addEventListener: jasmine
+        .createSpy('addEvent')
+        .and.callFake((eventName: string, cb: (e) => void) => {
+          if (eventName === 'input') {
+            triggertInputChange = cb;
+          }
+        }),
+      removeEventListener: jasmine.createSpy('removeEvent'),
+    };
+
+    document = { getElementById: (id: string) => input };
+    ajax = jasmine.createSpy('ajax').and.callFake((url: string) => of('foo bar'));
+  });
+
+  afterEach(() => {
+    jasmine.clock().uninstall();
+  });
+
+  it('should make an ajax call to the corrent endpoint', () => {
+    docRegionTypeahead(document, ajax);
+    triggertInputChange({ target: { value: 'foo' } });
+    jasmine.clock().tick(11);
+    expect(ajax).toHaveBeenCalledWith('/api/endpoint?search=foo');
+  });
+
+  it('should not make an ajax call, when the input length < 3', () => {
+    docRegionTypeahead(document, ajax);
+    triggertInputChange({ target: { value: '' } });
+    jasmine.clock().tick(11);
+    expect(ajax).not.toHaveBeenCalled();
+    triggertInputChange({ target: { value: 'fo' } });
+    jasmine.clock().tick(11);
+    expect(ajax).not.toHaveBeenCalled();
+  });
+
+  it('should not make an ajax call for intermediate values when debouncing', () => {
+    docRegionTypeahead(document, ajax);
+    triggertInputChange({ target: { value: 'foo' } });
+    jasmine.clock().tick(9);
+    triggertInputChange({ target: { value: 'bar' } });
+    jasmine.clock().tick(9);
+    triggertInputChange({ target: { value: 'baz' } });
+    jasmine.clock().tick(9);
+    triggertInputChange({ target: { value: 'qux' } });
+    expect(ajax).not.toHaveBeenCalled();
+    jasmine.clock().tick(10);
+    expect(ajax).toHaveBeenCalledTimes(1);
+    expect(ajax).toHaveBeenCalledWith('/api/endpoint?search=qux');
+  });
+
+  it('should not make an ajax call, when the input value has not changed', () => {
+    docRegionTypeahead(document, ajax);
+    triggertInputChange({ target: { value: 'foo' } });
+    jasmine.clock().tick(11);
+    expect(ajax).toHaveBeenCalled();
+    ajax.calls.reset();
+    triggertInputChange({ target: { value: 'foo' } });
+    jasmine.clock().tick(11);
+    expect(ajax).not.toHaveBeenCalled();
+  });
+});

aio/content/examples/practical-observable-usage/src/typeahead.ts

@@ -1,18 +1,32 @@
-import { fromEvent } from 'rxjs';
-import { ajax } from 'rxjs/ajax';
-import { debounceTime, distinctUntilChanged, filter, map, switchMap } from 'rxjs/operators';
+/*
+  Because of how the code is merged together using the doc regions,
+  we need to indent the imports with the function below.
+*/
+// #docplaster
+// #docregion
+  import { fromEvent } from 'rxjs';
+  import { ajax } from 'rxjs/ajax';
+  import { debounceTime, distinctUntilChanged, filter, map, switchMap } from 'rxjs/operators';
 
+// #enddocregion
+/* tslint:disable:no-shadowed-variable */
+/* tslint:disable:align */
+export function docRegionTypeahead(document, ajax) {
+  // #docregion
+  const searchBox = document.getElementById('search-box');
 
-const searchBox = document.getElementById('search-box');
+  const typeahead = fromEvent(searchBox, 'input').pipe(
+    map((e: KeyboardEvent) => (e.target as HTMLInputElement).value),
+    filter(text => text.length > 2),
+    debounceTime(10),
+    distinctUntilChanged(),
+    switchMap(searchTerm => ajax(`/api/endpoint?search=${searchTerm}`))
+  );
 
-const typeahead = fromEvent(searchBox, 'input').pipe(
-  map((e: KeyboardEvent) => (e.target as HTMLInputElement).value),
-  filter(text => text.length > 2),
-  debounceTime(10),
-  distinctUntilChanged(),
-  switchMap(() => ajax('/api/endpoint'))
-);
+  typeahead.subscribe(data => {
+    // Handle the data from the API
+  });
 
-typeahead.subscribe(data => {
- // Handle the data from the API
-});
+  // #enddocregion
+  return typeahead;
+}

aio/content/examples/service-worker-getting-started/src/app/handle-unrecoverable-state.service.ts

@@ -0,0 +1,17 @@
+import { Injectable } from '@angular/core';
+import { SwUpdate } from '@angular/service-worker';
+
+function notifyUser(message: string): void { }
+
+// #docregion sw-unrecoverable-state
+@Injectable()
+export class HandleUnrecoverableStateService {
+  constructor(updates: SwUpdate) {
+    updates.unrecoverable.subscribe(event => {
+      notifyUser(
+        `An error occurred that we cannot recover from:\n${event.reason}\n\n` +
+        'Please reload the page.');
+    });
+  }
+}
+// #enddocregion sw-unrecoverable-state

aio/content/examples/testing/src/app/demo/demo.testbed.spec.ts

@@ -28,7 +28,7 @@ import {
   ComponentFixture, fakeAsync, inject, TestBed, tick, waitForAsync
 } from '@angular/core/testing';
 
-import { addMatchers, newEvent, click } from '../../testing';
+import { addMatchers, click } from '../../testing';
 
 export class NotProvided extends ValueService { /* example below */ }
 beforeEach(addMatchers);
@@ -274,9 +274,11 @@ describe('demo (with TestBed):', () => {
         expect(comp.name).toBe(expectedOrigName,
           `comp.name should still be ${expectedOrigName} after value change, before binding happens`);
 
-        // dispatch a DOM event so that Angular learns of input value change.
+        // Dispatch a DOM event so that Angular learns of input value change.
         // then wait while ngModel pushes input.box value to comp.name
-        input.dispatchEvent(newEvent('input'));
+        // In older browsers, such as IE, you might need a CustomEvent instead. See
+        // https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent/CustomEvent#Polyfill
+        input.dispatchEvent(new Event('input'));
         return fixture.whenStable();
       })
         .then(() => {
@@ -312,9 +314,11 @@ describe('demo (with TestBed):', () => {
       expect(comp.name).toBe(expectedOrigName,
         `comp.name should still be ${expectedOrigName} after value change, before binding happens`);
 
-      // dispatch a DOM event so that Angular learns of input value change.
+      // Dispatch a DOM event so that Angular learns of input value change.
       // then wait a tick while ngModel pushes input.box value to comp.name
-      input.dispatchEvent(newEvent('input'));
+      // In older browsers, such as IE, you might need a CustomEvent instead. See
+      // https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent/CustomEvent#Polyfill
+      input.dispatchEvent(new Event('input'));
       tick();
       expect(comp.name).toBe(expectedNewName,
         `After ngModel updates the model, comp.name should be ${expectedNewName} `);
@@ -335,10 +339,12 @@ describe('demo (with TestBed):', () => {
       // simulate user entering new name in input
       input.value = inputText;
 
-      // dispatch a DOM event so that Angular learns of input value change.
+      // Dispatch a DOM event so that Angular learns of input value change.
       // then wait a tick while ngModel pushes input.box value to comp.text
       // and Angular updates the output span
-      input.dispatchEvent(newEvent('input'));
+      // In older browsers, such as IE, you might need a CustomEvent instead. See
+      // https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent/CustomEvent#Polyfill
+      input.dispatchEvent(new Event('input'));
       tick();
       fixture.detectChanges();
       expect(span.textContent).toBe(expectedText, 'output span');

aio/content/examples/testing/src/app/hero/hero-detail.component.spec.ts

@@ -3,7 +3,7 @@ import { ComponentFixture, fakeAsync, inject, TestBed, tick, waitForAsync } from
 import { Router } from '@angular/router';
 
 import {
-  ActivatedRoute, ActivatedRouteStub, asyncData, click, newEvent
+  ActivatedRoute, ActivatedRouteStub, asyncData, click
 } from '../../testing';
 
 import { Hero } from '../model/hero';
@@ -99,7 +99,10 @@ function overrideSetup() {
        const newName = 'New Name';
 
        page.nameInput.value = newName;
-       page.nameInput.dispatchEvent(newEvent('input'));  // tell Angular
+
+       // In older browsers, such as IE, you might need a CustomEvent instead. See
+       // https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent/CustomEvent#Polyfill
+       page.nameInput.dispatchEvent(new Event('input')); // tell Angular
 
        expect(component.hero.name).toBe(newName, 'component hero has new name');
        expect(hdsSpy.testHero.name).toBe(origName, 'service hero unchanged before save');
@@ -197,9 +200,10 @@ function heroModuleSetup() {
       // simulate user entering a new name into the input box
       nameInput.value = 'quick BROWN  fOx';
 
-      // dispatch a DOM event so that Angular learns of input value change.
-      // use newEvent utility function (not provided by Angular) for better browser compatibility
-      nameInput.dispatchEvent(newEvent('input'));
+      // Dispatch a DOM event so that Angular learns of input value change.
+      // In older browsers, such as IE, you might need a CustomEvent instead. See
+      // https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent/CustomEvent#Polyfill
+      nameInput.dispatchEvent(new Event('input'));
 
       // Tell Angular to update the display binding through the title pipe
       fixture.detectChanges();

aio/content/examples/testing/src/app/hero/hero-list.component.spec.ts

@@ -6,7 +6,7 @@ import { DebugElement } from '@angular/core';
 
 import { Router } from '@angular/router';
 
-import { addMatchers, newEvent } from '../../testing';
+import { addMatchers } from '../../testing';
 import { HeroService } from '../model/hero.service';
 import { getTestHeroes, TestHeroService } from '../model/testing/test-hero.service';
 
@@ -53,7 +53,10 @@ describe('HeroListComponent', () => {
   it('should select hero on click', fakeAsync(() => {
        const expectedHero = HEROES[1];
        const li = page.heroRows[1];
-       li.dispatchEvent(newEvent('click'));
+
+       // In older browsers, such as IE, you might need a CustomEvent instead. See
+       // https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent/CustomEvent#Polyfill
+       li.dispatchEvent(new Event('click'));
        tick();
        // `.toEqual` because selectedHero is clone of expectedHero; see FakeHeroService
        expect(comp.selectedHero).toEqual(expectedHero);
@@ -62,7 +65,10 @@ describe('HeroListComponent', () => {
   it('should navigate to selected hero detail on click', fakeAsync(() => {
        const expectedHero = HEROES[1];
        const li = page.heroRows[1];
-       li.dispatchEvent(newEvent('click'));
+
+       // In older browsers, such as IE, you might need a CustomEvent instead. See
+       // https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent/CustomEvent#Polyfill
+       li.dispatchEvent(new Event('click'));
        tick();
 
        // should have navigated

aio/content/examples/testing/src/app/shared/highlight.directive.spec.ts

@@ -3,7 +3,6 @@ import { ComponentFixture, TestBed } from '@angular/core/testing';
 import { By } from '@angular/platform-browser';
 
 import { HighlightDirective } from './highlight.directive';
-import { newEvent } from '../../testing';
 
 // #docregion test-component
 @Component({
@@ -59,9 +58,12 @@ describe('HighlightDirective', () => {
     const input = des[2].nativeElement as HTMLInputElement;
     expect(input.style.backgroundColor).toBe('cyan', 'initial backgroundColor');
 
-    // dispatch a DOM event so that Angular responds to the input value change.
     input.value = 'green';
-    input.dispatchEvent(newEvent('input'));
+
+    // Dispatch a DOM event so that Angular responds to the input value change.
+    // In older browsers, such as IE, you might need a CustomEvent instead. See
+    // https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent/CustomEvent#Polyfill
+    input.dispatchEvent(new Event('input'));
     fixture.detectChanges();
 
     expect(input.style.backgroundColor).toBe('green', 'changed backgroundColor');

aio/content/examples/testing/src/testing/index.ts

@@ -14,18 +14,6 @@ export function advance(f: ComponentFixture<any>): void {
   f.detectChanges();
 }
 
-/**
- * Create custom DOM event the old fashioned way
- *
- * https://developer.mozilla.org/en-US/docs/Web/API/Event/initEvent
- * Although officially deprecated, some browsers (phantom) don't accept the preferred "new Event(eventName)"
- */
-export function newEvent(eventName: string, bubbles = false, cancelable = false) {
-  const evt = document.createEvent('CustomEvent');  // MUST be 'CustomEvent'
-  evt.initCustomEvent(eventName, bubbles, cancelable, null);
-  return evt;
-}
-
 // See https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent/button
 // #docregion click-event
 /** Button events to pass to `DebugElement.triggerEventHandler` for RouterLink event handler */

aio/content/guide/bootstrapping.md

@@ -18,8 +18,6 @@ When you use the [Angular CLI](cli) command `ng new` to generate an app, the def
 /* JavaScript imports */
 import { BrowserModule } from '@angular/platform-browser';
 import { NgModule } from '@angular/core';
-import { FormsModule } from '@angular/forms';
-import { HttpClientModule } from '@angular/common/http';
 
 import { AppComponent } from './app.component';
 
@@ -29,9 +27,7 @@ import { AppComponent } from './app.component';
     AppComponent
   ],
   imports: [
-    BrowserModule,
-    FormsModule,
-    HttpClientModule
+    BrowserModule
   ],
   providers: [],
   bootstrap: [AppComponent]
@@ -120,9 +116,6 @@ Now you could use your `ItemDirective` in a component. This example uses `AppMod
 
 Remember, components, directives, and pipes belong to one module only. You only need to declare them once in your app because you share them by importing the necessary modules. This saves you time and helps keep your app lean.
 
-
-
-
 {@a imports}
 
 ## The `imports` array
@@ -130,6 +123,12 @@ Remember, components, directives, and pipes belong to one module only. You only
 The module's `imports` array appears exclusively in the `@NgModule` metadata object.
 It tells Angular about other NgModules that this particular module needs to function properly.
 
+<code-example
+    path="bootstrapping/src/app/app.module.ts"
+    region="imports"
+    header="src/app/app.module.ts (excerpt)">
+</code-example>
+
 This list of modules are those that export components, directives, or pipes
 that component templates in this module reference. In this case, the component is
 `AppComponent`, which references components, directives, or pipes in `BrowserModule`,
@@ -138,6 +137,8 @@ A component template can reference another component, directive,
 or pipe when the referenced class is declared in this module or
 the class was imported from another module.
 
+
+
 {@a bootstrap-array}
 
 ## The `providers` array

aio/content/guide/deprecations.md

@@ -38,7 +38,6 @@ v9 - v12
 | `@angular/bazel`              | [`Bazel builder and schematics`](#bazelbuilder)                               | v10 |
 | `@angular/common`             | [`ReflectiveInjector`](#reflectiveinjector)                                   | <!--v8--> v11 |
 | `@angular/common`             | [`CurrencyPipe` - `DEFAULT_CURRENCY_CODE`](api/common/CurrencyPipe#currency-code-deprecation) | <!--v9--> v11 |
-| `@angular/core`               | [`CollectionChangeRecord`](#core)                                             | <!--v7--> v11 |
 | `@angular/core`               | [`DefaultIterableDiffer`](#core)                                              | <!--v7--> v11 |
 | `@angular/core`               | [`ReflectiveKey`](#core)                                                      | <!--v8--> v11 |
 | `@angular/core`               | [`RenderComponentType`](#core)                                                | <!--v7--> v11 |
@@ -89,7 +88,6 @@ Tip: In the [API reference section](api) of this doc site, deprecated APIs are i
 
 | API | Replacement | Deprecation announced | Notes |
 | --- | ----------- | --------------------- | ----- |
-| [`CollectionChangeRecord`](api/core/CollectionChangeRecord) | [`IterableChangeRecord`](api/core/IterableChangeRecord) | v4 | none |
 | [`DefaultIterableDiffer`](api/core/DefaultIterableDiffer) | n/a | v4 | Not part of public API. |
 | [`ReflectiveInjector`](api/core/ReflectiveInjector) | [`Injector.create`](api/core/Injector#create)  | v5 | See [`ReflectiveInjector`](#reflectiveinjector) |
 | [`ReflectiveKey`](api/core/ReflectiveKey) | none | v5 | none |

aio/content/guide/elements.md

@@ -119,7 +119,14 @@ The recently-developed [custom elements](https://developer.mozilla.org/en-US/doc
 
 In browsers that support Custom Elements natively, the specification requires developers use ES2015 classes to define Custom Elements - developers can opt-in to this by setting the `target: "es2015"` property in their project's [TypeScript configuration file](/guide/typescript-configuration). As Custom Element and ES2015 support may not be available in all browsers, developers can instead choose to use a polyfill to support older browsers and ES5 code.
 
-Use the [Angular CLI](cli) to automatically set up your project with the correct polyfill: `ng add @angular/elements --project=*your_project_name*`.
+Use the [Angular CLI](cli) to automatically set up your project with the correct polyfill: 
+
+<code-example language="sh">
+
+ng add @angular/elements --project=*your_project_name*
+
+</code-example>
+
 - For more information about polyfills, see [polyfill documentation](https://www.webcomponents.org/polyfills).
 
 - For more information about Angular browser support, see [Browser Support](guide/browser-support).

aio/content/guide/glossary.md

@@ -627,6 +627,11 @@ The [npm package manager](https://docs.npmjs.com/getting-started/what-is-npm) is
 
 Learn more about how Angular uses [Npm Packages](guide/npm-packages).
 
+{@ ngc}
+## ngc
+`ngc` is a Typescript-to-Javascript transpiler that processes Angular decorators, metadata, and templates, and emits JavaScript code.
+The most recent implementation is internally refered to as `ngtsc` because it's a minimalistic wrapper around the TypeScript compiler `tsc` that adds a transform for processing Angular code.
+
 {@a O}
 
 {@a observable}

aio/content/guide/releases.md

@@ -94,7 +94,7 @@ All of our major releases are supported for 18 months.
 
 * 6 months of *active support*, during which regularly-scheduled updates and patches are released.
 
-* 12 months of *long-term support (LTS)*, during which only critical fixes and security patches are released.
+* 12 months of *long-term support (LTS)*, during which only [critical fixes and security patches](#lts-fixes) are released.
 
 The following table provides the status for Angular versions under support.
 
@@ -107,6 +107,13 @@ Version | Status | Released     | Active Ends  | LTS Ends
 
 Angular versions ^4.0.0, ^5.0.0, ^6.0.0 and ^7.0.0 are no longer under support.
 
+### LTS fixes
+
+As a general rule, a fix is considered for an LTS version if it resolves one of:
+
+* a newly identified security vulnerability,
+* a regression, since the start of LTS, caused by a 3rd party change, such as a new browser version.
+
 {@a deprecation}
 ## Deprecation practices
 

aio/content/guide/service-worker-communications.md

@@ -67,6 +67,33 @@ Therefore, it is recommended to reload the page once the promise returned by `ac
 
 </div>
 
+### Handling an unrecoverable state
+
+In some cases, the version of the app used by the service worker to serve a client might be in a broken state that cannot be recovered from without a full page reload.
+
+For example, imagine the following scenario:
+- A user opens the app for the first time and the service worker caches the latest version of the app.
+  Let's assume the app's cached assets include `index.html`, `main.<main-hash-1>.js` and `lazy-chunk.<lazy-hash-1>.js`.
+- The user closes the app and does not open it for a while.
+- After some time, a new version of the app is deployed to the server.
+  This newer version includes the files `index.html`, `main.<main-hash-2>.js` and `lazy-chunk.<lazy-hash-2>.js` (note that the hashes are different now, because the content of the files has changed).
+  The old version is no longer available on the server.
+- In the meantime, the user's browser decides to evict `lazy-chunk.<lazy-hash-1>.js` from its cache.
+  Browsers may decide to evict specific (or all) resources from a cache in order to reclaim disk space.
+- The user opens the app again.
+  The service worker serves the latest version known to it at this point, namely the old version (`index.html` and `main.<main-hash-1>.js`).
+- At some later point, the app requests the lazy bundle, `lazy-chunk.<lazy-hash-1>.js`.
+- The service worker is unable to find the asset in the cache (remember that the browser evicted it).
+  Nor is it able to retrieve it from the server (since the server now only has `lazy-chunk.<lazy-hash-2>.js` from the newer version).
+
+In the above scenario, the service worker is not able to serve an asset that would normally be cached.
+That particular app version is broken and there is no way to fix the state of the client without reloading the page.
+In such cases, the service worker notifies the client by sending an `UnrecoverableStateEvent` event.
+You can subscribe to `SwUpdate#unrecoverable` to be notified and handle these errors.
+
+<code-example path="service-worker-getting-started/src/app/handle-unrecoverable-state.service.ts" header="handle-unrecoverable-state.service.ts" region="sw-unrecoverable-state"></code-example>
+
+
 ## More on Angular service workers
 
 You may also be interested in the following:

aio/content/guide/service-worker-config.md

@@ -267,6 +267,12 @@ By default, these criteria are:
 1. The URL must not contain a file extension (i.e. a `.`) in the last path segment.
 2. The URL must not contain `__`.
 
+<div class="alert is-helpful">
+
+To configure whether navigation requests are sent through to the network or not, see the [navigationRequestStrategy](#navigation-request-strategy) section.
+
+</div>
+
 ### Matching navigation request URLs
 
 While these default criteria are fine in most cases, it is sometimes desirable to configure different rules. For example, you may want to ignore specific routes (that are not part of the Angular app) and pass them through to the server.
@@ -285,3 +291,32 @@ If the field is omitted, it defaults to:
   '!/**/*__*/**',  // Exclude URLs containing `__` in any other segment.
 ]
 ```
+
+{@a navigation-request-strategy}
+
+## `navigationRequestStrategy`
+
+This optional property enables you to configure how the service worker handles navigation requests:
+
+```json
+{
+  "navigationRequestStrategy": "freshness"
+}
+```
+
+Possible values:
+
+- `'performance'`: The default setting. Serves the specified [index file](#index-file), which is typically cached.
+- `'freshness'`: Passes the requests through to the network and falls back to the `performance` behavior when offline.
+  This value is useful when the server redirects the navigation requests elsewhere using an HTTP redirect (3xx status code).
+  Reasons for using this value include:
+    - Redirecting to an authentication website when authentication is not handled by the application.
+    - Redirecting specific URLs to avoid breaking existing links/bookmarks after a website redesign.
+    - Redirecting to a different website, such as a server-status page, while a page is temporarily down.
+
+<div class="alert is-important">
+
+The `freshness` strategy usually results in more requests sent to the server, which can increase response latency.
+It is recommended that you use the default performance strategy whenever possible.
+
+</div>

aio/content/guide/user-input.md

@@ -324,5 +324,5 @@ These techniques are useful for small-scale demonstrations, but they
 quickly become verbose and clumsy when handling large amounts of user input.
 Two-way data binding is a more elegant and compact way to move
 values between data entry fields and model properties.
-The next page, `Forms`, explains how to write
+The [`Forms`](guide/forms-overview) page explains how to write
 two-way bindings with `NgModel`.

aio/content/guide/using-libraries.md

@@ -32,7 +32,7 @@ To do this:
 
 1. Create a `typings.d.ts` file in your `src/` folder. This file is automatically included as global type definition.
 
-2. Add the following code in `src/typings.d.ts`.
+2. Add the following code in `src/typings.d.ts`:
 
 ```
 declare module 'host' {
@@ -45,7 +45,7 @@ declare module 'host' {
 }
 ```
 
-3. In the component or file that uses the library, add the following code.
+3. In the component or file that uses the library, add the following code:
 
 ```
 import * as host from 'host';
@@ -129,7 +129,7 @@ interface JQuery {
 }
 ```
 
-If don't add the interface for the script-defined extension, your IDE shows an error:
+If you don't add the interface for the script-defined extension, your IDE shows an error:
 
 ```
 [TS][Error] Property 'myPlugin' does not exist on type 'JQuery'

aio/content/marketing/contributors.json

@@ -53,6 +53,9 @@
   },
   "kyliau": {
     "name": "Keen Yee Liau",
+    "twitter": "liauky",
+    "website": "https://github.com/kyliau",
+    "bio": "Keen works on language service and CLI. He also maintains Karma and Protractor.",
     "groups": ["Angular"],
     "lead": "igorminar",
     "picture": "kyliau.jpg"

aio/content/marketing/events.html

@@ -3,162 +3,5 @@
 </header>
 
 <article class="events-container">
-  <p>Where we'll be presenting:</p>
-  <table class="is-full-width">
-    <thead>
-      <tr>
-        <th>Event</th>
-        <th>Location</th>
-        <th>Date</th>
-      </tr>
-    </thead>
-    <tbody>
-    </tbody>
-  </table>
-
-  <p>Where we already presented:</p>
-  <table class="is-full-width">
-    <thead>
-      <tr>
-        <th>Event</th>
-        <th>Location</th>
-        <th>Date</th>
-      </tr>
-    </thead>
-    <tbody>
-      <!-- ng-vikings 2020 -->
-      <tr>
-        <th><a href="https://ngvikings.org/" title="ngVikings">ngVikings</a></th>
-        <td>Oslo, Norway</td>
-        <td>May 25-26 conference, 27 workshops, 2020</td>
-      </tr>
-      <!-- ng-conf 2020 -->
-      <tr>
-        <th><a href="https://ng-conf.org/" title="ng-conf">ng-conf</a></th>
-        <td>Salt Lake City, Utah</td>
-        <td>April 1-3, 2020</td>
-      </tr>
-      <!-- ngIndia 2020 -->
-      <tr>
-        <th><a href="https://www.ng-ind.com/" title="ngIndia">ngIndia</a></th>
-        <td>Delhi, India</td>
-        <td>Feb 29, 2020</td>
-      </tr>
-      <!-- ReactiveConf 2019 -->
-      <tr>
-        <th><a href="https://reactiveconf.com/" title="ReactiveConf">ReactiveConf</a></th>
-        <td>Prague, Czech Republic</td>
-        <td>October 30 - November 1, 2019</td>
-      </tr>
-      <!-- NG Rome 2019-->
-      <tr>
-        <th>
-          <a href="https://ngrome.io" title="NG Rome MMXIX - The Italian Angular Conference">NG Rome MMXIX</a>
-        </th>
-        <td>Rome, Italy</td>
-        <td>Oct 6th workshops, 7th conference, 2019</td>
-      </tr>
-      <!-- AngularConnect 2019-->
-      <tr>
-        <th><a href="https://www.angularconnect.com/?utm_source=angular.io&utm_medium=referral"
-            title="AngularConnect">AngularConnect</a></th>
-        <td>London, UK</td>
-        <td>September 19-20, 2019</td>
-      </tr>
-      <!-- NG-DE 2019-->
-      <tr>
-        <th><a href="https://ng-de.org/" title="NG-DE">NG-DE</a></th>
-        <td>Berlin, Germany</td>
-        <td>August 29th workshops, 30-31 conference, 2019</td>
-      </tr>
-      <!-- ngJapan-->
-      <tr>
-        <th><a href="https://ngjapan.org" title="ng-japan">ng-japan</a></th>
-        <td>Tokyo, Japan</td>
-        <td>July 13, 2019</td>
-      </tr>
-      <!-- ngVikings 2019-->
-      <tr>
-        <th><a href="https://ngvikings.org/" title="ngVikings">ngVikings</a></th>
-        <td>Copenhagen, Denmark</td>
-        <td>May 26 (workshops), 27-28 (conference), 2019</td>
-      </tr>
-      <!-- ng-conf 2019-->
-      <tr>
-        <th><a href="https://ng-conf.org/" title="ng-conf">ng-conf</a></th>
-        <td>Salt Lake City, Utah</td>
-        <td>May 1-3, 2019</td>
-      </tr>
-      <!-- ng-India 2019-->
-      <tr>
-        <th><a href="https://www.ng-ind.com/" title="ng-India">ng-India</a></th>
-        <td>Gurgaon, India</td>
-        <td>February 23, 2019</td>
-      </tr>
-      <!-- ngAtlanta 2019 -->
-      <tr>
-        <th><a href="https://ng-atl.org/" title="ngAtlanta">ngAtlanta</a></th>
-        <td>Atlanta, Georgia</td>
-        <td>January 9-12, 2019</td>
-      </tr>
-      <!-- AngularConnect-->
-      <tr>
-        <th>
-          <a href="https://past.angularconnect.com/2018" title="AngularConnect">AngularConnect</a>
-        </th>
-        <td>London, United Kingdom</td>
-        <td>November 5-7, 2018</td>
-      </tr>
-      <!-- ReactiveConf -->
-      <tr>
-        <th><a href="https://reactiveconf.com/" title="ReactiveConf">ReactiveConf</a></th>
-        <td>Prague, Czech Republic</td>
-        <td>October 29-31, 2018</td>
-      </tr>
-      <!-- AngularMix -->
-      <tr>
-        <th><a href="https://angularmix.com/" title="AngularMix">AngularMix</a></th>
-        <td>Orlando, Florida</td>
-        <td>October 10-12, 2018</td>
-      </tr>
-      <!-- Angular Conf Australia-->
-      <tr>
-        <th>
-          <a href="https://www.angularconf.com.au/" title="Angular Conf Australia">Angular Conf Australia</a>
-        </th>
-        <td>Melbourne, Australia</td>
-        <td>Jun 22, 2018</td>
-      </tr>
-      <!-- ngJapan-->
-      <tr>
-        <th><a href="https://ngjapan.org/en.html" title="ng-japan">ng-japan</a></th>
-        <td>Tokyo, Japan</td>
-        <td>Jun 16, 2018</td>
-      </tr>
-      <!-- WeRDevs-->
-      <tr>
-        <th><a href="https://www.wearedevelopers.com/" title="WeAreDevs">WeAreDevelopers</a></th>
-        <td>Vienna, Austria</td>
-        <td>May 16-18, 2018</td>
-      </tr>
-      <!-- ngconf 2018-->
-      <tr>
-        <th><a href="https://www.ng-conf.org/" title="ng-conf">ng-conf</a></th>
-        <td>Salt Lake City, Utah</td>
-        <td>April 18-20, 2018</td>
-      </tr>
-      <!-- ngVikings-->
-      <tr>
-        <th><a href="https://ngvikings.org/" title="ngVikings">ngVikings</a></th>
-        <td>Helsinki, Finland</td>
-        <td>March 1-2, 2018</td>
-      </tr>
-      <!-- ngAtlanta-->
-      <tr>
-        <th><a href="http://ng-atl.org/" title="ngAtlanta">ngAtlanta</a></th>
-        <td>Atlanta, Georgia</td>
-        <td>January 30, 2018</td>
-      </tr>
-    </tbody>
-  </table>
+  <aio-events></aio-events>
 </article>

aio/content/marketing/events.json

@@ -0,0 +1,236 @@
+[
+  {
+    "name": "ng-china",
+    "location": "Online",
+    "linkUrl": "https://ng-china.org/",
+    "date": {
+      "start": "2020-11-21",
+      "end": "2020-11-22"
+    }
+  },
+  {
+    "name": "EnterpriseNG",
+    "location": "Online",
+    "linkUrl": "https://www.ng-conf.org/",
+    "date": {
+      "start": "2020-11-19",
+      "end": "2020-11-20"
+    }
+  },
+  {
+    "name": "ngrome",
+    "location": "Online",
+    "linkUrl": "https://ngrome.io/",
+    "date": {
+      "start": "2020-10-20",
+      "end": "2020-10-20"
+    }
+  },
+  {
+    "name": "ngVikings",
+    "location": "Oslo, Norway",
+    "linkUrl": "https://ngvikings.org/",
+    "date": {
+      "start": "2020-05-25",
+      "end": "2020-05-26"
+    },
+    "workshopsDate": {
+      "start": "2020-05-27",
+      "end": "2020-05-27"
+    }
+  },
+  {
+    "name": "ng-conf",
+    "location": "Salt Lake City, Utah",
+    "linkUrl": "https://ng-conf.org/",
+    "date": {
+      "start": "2020-04-01",
+      "end": "2020-04-03"
+    }
+  },
+  {
+    "name": "ngIndia",
+    "location": "Delhi, India",
+    "linkUrl": "https://www.ng-ind.com/",
+    "date": {
+      "start": "2020-02-29",
+      "end": "2020-02-29"
+    }
+  },
+  {
+    "name": "ReactiveConf",
+    "location": "Prague, Czech Republic",
+    "linkUrl": "https://reactiveconf.com/",
+    "date": {
+      "start": "2019-10-30",
+      "end": "2019-11-01"
+    }
+  },
+  {
+    "name": "NG Rome MMXIX",
+    "location": "Rome, Italy",
+    "linkUrl": "https://ngrome.io",
+    "tooltip": "NG Rome MMXIX - The Italian Angular Conference",
+    "date": {
+      "start": "2019-10-07",
+      "end": "2019-10-07"
+    },
+    "workshopsDate": {
+      "start": "2019-10-06",
+      "end": "2019-10-06"
+    }
+  },
+  {
+    "name": "AngularConnect",
+    "location": "London, UK",
+    "linkUrl": "https://www.angularconnect.com/?utm_source=angular.io&utm_medium=referral",
+    "date": {
+      "start": "2019-09-19",
+      "end": "2019-09-20"
+    }
+  },
+  {
+    "name": "NG-DE",
+    "location": "Berlin, Germany",
+    "linkUrl": "https://ng-de.org/",
+    "date": {
+      "start": "2019-08-30",
+      "end": "2019-08-31"
+    },
+    "workshopsDate": {
+      "start": "2019-08-29",
+      "end": "2019-08-29"
+    }
+  },
+  {
+    "name": "ng-japan",
+    "location": "Tokyo, Japan",
+    "linkUrl": "https://ngjapan.org/",
+    "date": {
+      "start": "2019-07-13",
+      "end": "2019-07-13"
+    }
+  },
+  {
+    "name": "ngVikings",
+    "location": "Copenhagen, Denmark",
+    "linkUrl": "https://ngvikings.org/",
+    "date": {
+      "start": "2019-05-27",
+      "end": "2019-05-28"
+    },
+    "workshopsDate": {
+      "start": "2019-05-26",
+      "end": "2019-05-26"
+    }
+  },
+  {
+    "name": "ng-conf",
+    "location": "Salt Lake City, Utah",
+    "linkUrl": "https://ng-conf.org/",
+    "date": {
+      "start": "2019-05-01",
+      "end": "2019-05-03"
+    }
+  },
+  {
+    "name": "ng-India",
+    "location": "Gurgaon, India",
+    "linkUrl": "https://www.ng-ind.com/",
+    "date": {
+      "start": "2019-02-23",
+      "end": "2019-02-23"
+    }
+  },
+  {
+    "name": "ngAtlanta",
+    "location": "Atlanta, Georgia",
+    "linkUrl": "https://ng-atl.org/",
+    "date": {
+      "start": "2019-01-09",
+      "end": "2019-01-12"
+    }
+  },
+  {
+    "name": "AngularConnect",
+    "location": "London, United Kingdom",
+    "linkUrl": "https://past.angularconnect.com/2018",
+    "date": {
+      "start": "2018-11-05",
+      "end": "2018-11-07"
+    }
+  },
+  {
+    "name": "ReactiveConf",
+    "location": "Prague, Czech Republic",
+    "linkUrl": "https://reactiveconf.com/",
+    "date": {
+      "start": "2018-10-29",
+      "end": "2018-10-31"
+    }
+  },
+  {
+    "name": "AngularMix",
+    "location": "Orlando, Florida",
+    "linkUrl": "https://angularmix.com/",
+    "date": {
+      "start": "2018-10-10",
+      "end": "2018-10-12"
+    }
+  },
+  {
+    "name": "Angular Conf Australia",
+    "location": "Melbourne, Australia",
+    "linkUrl": "https://www.angularconf.com.au/",
+    "date": {
+      "start": "2018-06-22",
+      "end": "2018-06-22"
+    }
+  },
+  {
+    "name": "ng-japan",
+    "location": "Tokyo, Japan",
+    "linkUrl": "https://ngjapan.org/en.html",
+    "date": {
+      "start": "2018-06-16",
+      "end": "2018-06-16"
+    }
+  },
+  {
+    "name": "WeAreDevelopers",
+    "location": "Vienna, Austria",
+    "linkUrl": "https://www.wearedevelopers.com/",
+    "tooltip": "WeAreDevs",
+    "date": {
+      "start": "2018-05-16",
+      "end": "2018-05-18"
+    }
+  },
+  {
+    "name": "ng-conf",
+    "location": "Salt Lake City, Utah",
+    "linkUrl": "https://ng-conf.org/",
+    "date": {
+      "start": "2018-04-18",
+      "end": "2018-04-20"
+    }
+  },
+  {
+    "name": "ngVikings",
+    "location": "Helsinki, Finland",
+    "linkUrl": "https://ngvikings.org/",
+    "date": {
+      "start": "2018-03-01",
+      "end": "2018-03-02"
+    }
+  },
+  {
+    "name": "ngAtlanta",
+    "location": "Atlanta, Georgia",
+    "linkUrl": "https://ng-atl.org/",
+    "date": {
+      "start": "2018-01-30",
+      "end": "2018-01-30"
+    }
+  }
+]

aio/content/navigation.json

@@ -56,35 +56,35 @@
       "tooltip": "Set up your environment and learn basic concepts",
       "children": [
         {
-          "title": "Try it",
-          "tooltip": "Examine and work with a ready-made sample app, with no setup.",
-          "children": [
-            {
-              "url": "start",
-              "title": "A Sample App",
-              "tooltip": "Take a look at Angular's component model, template syntax, and component communication."
-            },
-            {
-              "url": "start/start-routing",
-              "title": "In-app Navigation",
-              "tooltip": "Navigate among different page views using the browser's URL."
-            },
-            {
-              "url": "start/start-data",
-              "title": "Manage Data",
-              "tooltip": "Use services and access external data via HTTP."
-            },
-            {
-              "url": "start/start-forms",
-              "title": "Forms for User Input",
-              "tooltip": "Learn about fetching and managing data from users with forms."
-            },
-            {
-              "url": "start/start-deployment",
-              "title": "Deployment",
-              "tooltip": "Move to local development, or deploy your application to Firebase or your own server."
-            }
-          ]
+            "title": "Try it",
+            "tooltip": "Examine and work with a ready-made sample app, with no setup.",
+            "children": [
+              {
+                "url": "start",
+                "title": "Getting started",
+                "tooltip": "Take a look at Angular's component model, template syntax, and component communication."
+              },
+              {
+                "url": "start/start-routing",
+                "title": "Adding navigation",
+                "tooltip": "Navigate among different page views using the browser's URL."
+              },
+              {
+                "url": "start/start-data",
+                "title": "Managing Data",
+                "tooltip": "Use services and access external data via HTTP."
+              },
+              {
+                "url": "start/start-forms",
+                "title": "Using Forms for User Input",
+                "tooltip": "Learn about fetching and managing data from users with forms."
+              },
+              {
+                "url": "start/start-deployment",
+                "title": "Deploying an application",
+                "tooltip": "Move to local development, or deploy your application to Firebase or your own server."
+              }
+            ]
         },
         {
           "url": "guide/setup-local",
@@ -101,11 +101,6 @@
           "title": "Components",
           "tooltip": "Building dynamic views with data binding",
           "children": [
-            {
-              "url": "guide/displaying-data",
-              "title": "Data binding",
-              "tooltip": "Property binding helps show app data in the UI."
-            },
             {
               "url": "guide/user-input",
               "title": "User Input",
@@ -542,27 +537,6 @@
       "title": "Tutorials",
       "tooltip": "End-to-end tutorials for learning Angular concepts and patterns.",
       "children": [
-        {
-          "title": "Routing",
-          "tooltip": "End-to-end tutorials for learning about Angular's router.",
-          "children": [
-            {
-              "url": "guide/router-tutorial",
-              "title": "Using Angular Routes in a Single-page Application",
-              "tooltip": "A tutorial that covers many patterns associated with Angular routing."
-            },
-            {
-              "url": "guide/router-tutorial-toh",
-              "title": "Router tutorial: tour of heroes",
-              "tooltip": "Explore how to use Angular's router. Based on the Tour of Heroes example."
-            }
-          ]
-        },
-        {
-          "url": "guide/forms",
-          "title": "Building a Template-driven Form",
-          "tooltip": "Create a template-driven form using directives and Angular template syntax."
-        },
         {
           "title": "Tutorial: Tour of Heroes",
           "tooltip": "The Tour of Heroes app is used as a reference point in many Angular examples.",
@@ -609,6 +583,32 @@
             }
           ]
         },
+        {
+          "title": "Routing",
+          "tooltip": "End-to-end tutorials for learning about Angular's router.",
+          "children": [
+            {
+              "url": "guide/router-tutorial",
+              "title": "Using Angular Routes in a Single-page Application",
+              "tooltip": "A tutorial that covers many patterns associated with Angular routing."
+            },
+            {
+              "url": "guide/router-tutorial-toh",
+              "title": "Router tutorial: tour of heroes",
+              "tooltip": "Explore how to use Angular's router. Based on the Tour of Heroes example."
+            }
+          ]
+        },
+        {
+          "url": "guide/forms",
+          "title": "Building a Template-driven Form",
+          "tooltip": "Create a template-driven form using directives and Angular template syntax."
+        },
+        {
+          "url": "guide/displaying-data",
+          "title": "Data binding",
+          "tooltip": "Property binding helps show app data in the UI."
+        },
         {
           "url": "guide/web-worker",
           "title": "Web Workers",
@@ -954,6 +954,11 @@
               "url": "guide/styleguide",
               "title": "Coding Style Guide",
               "tooltip": "Guidelines for writing Angular code."
+            },
+            {
+              "url": "guide/docs-style-guide",
+              "title": "Documentation Style Guide",
+              "tooltip": "Style guide for documentation authors."
             }
           ]
         }

aio/content/start/index.md

@@ -1,4 +1,4 @@
-# Part 1: Getting started with a basic Angular app
+# Getting started with a basic Angular app
 
 Welcome to Angular!
 

aio/content/start/start-data.md

@@ -1,4 +1,4 @@
-# Try it: Manage data
+# Managing data
 
 At the end of [In-app Navigation](start/start-routing "Try it: In-app Navigation"), the online store application has a product catalog with two views: a product list and product details.
 Users can click on a product name from the list to see details in a new view, with a distinct URL, or route.

aio/content/start/start-deployment.md

@@ -1,4 +1,4 @@
-# Try it: Deployment
+# Deploying an application
 
 
 To deploy your application, you have to compile it, and then host the JavaScript, CSS, and HTML on a web server. Built Angular applications are very portable and can live in any environment or served by any technology, such as Node, Java, .NET, PHP, and many others.

aio/content/start/start-forms.md

@@ -1,4 +1,4 @@
-# Try it: Use forms for user input
+# Using forms for user input
 
 At the end of [Managing Data](start/start-data "Try it: Managing Data"), the online store application has a product catalog and a shopping cart.
 

aio/content/start/start-routing.md

@@ -1,4 +1,4 @@
-# In-app navigation
+# Adding navigation
 
 At the end of [part 1](start "Get started with a basic Angular app"), the online store application has a basic product catalog.
 The app doesn't have any variable states or navigation.

aio/package.json

@@ -23,7 +23,7 @@
     "build-local-with-viewengine": "yarn ~~build",
     "prebuild-local-with-viewengine-ci": "node scripts/switch-to-viewengine && yarn setup-local-ci",
     "build-local-with-viewengine-ci": "yarn ~~build --progress=false",
-    "extract-cli-command-docs": "node tools/transforms/cli-docs-package/extract-cli-commands.js ef770f1cb",
+    "extract-cli-command-docs": "node tools/transforms/cli-docs-package/extract-cli-commands.js 800ba9271",
     "lint": "yarn check-env && yarn docs-lint && ng lint && yarn example-lint && yarn tools-lint",
     "test": "yarn check-env && ng test",
     "pree2e": "yarn check-env && yarn update-webdriver",

aio/src/app/custom-elements/element-registry.ts

@@ -40,6 +40,10 @@ export const ELEMENT_MODULE_LOAD_CALLBACKS_AS_ROUTES = [
   {
     selector: 'live-example',
     loadChildren: () => import('./live-example/live-example.module').then(m => m.LiveExampleModule)
+  },
+  {
+    selector: 'aio-events',
+    loadChildren: () => import('./events/events.module').then(m => m.EventsModule)
   }
 ];
 

aio/src/app/custom-elements/events/events.component.html

@@ -0,0 +1,43 @@
+<p>Where we'll be presenting:</p>
+<table class="is-full-width">
+  <thead>
+    <tr>
+      <th>Event</th>
+      <th>Location</th>
+      <th>Date</th>
+    </tr>
+  </thead>
+  <tbody >
+    <tr *ngFor="let event of upcomingEvents">
+      <th><a href="{{event.linkUrl}}" title="{{event.tooltip}}">{{event.name}}</a></th>
+      <td>{{event.location}}</td>
+      <td>
+        <div>
+          {{getEventDates(event)}}
+        </div>
+      </td>
+    </tr>
+  </tbody>
+</table>
+
+<p>Where we already presented:</p>
+<table class="is-full-width">
+  <thead>
+    <tr>
+      <th>Event</th>
+      <th>Location</th>
+      <th>Date</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr *ngFor="let event of pastEvents">
+      <th><a href="{{event.linkUrl}}" title="{{event.tooltip}}">{{event.name}}</a></th>
+      <td>{{event.location}}</td>
+      <td>
+        <div>
+          {{getEventDates(event)}}
+        </div>
+      </td>
+    </tr>
+  </tbody>
+</table>

aio/src/app/custom-elements/events/events.component.spec.ts

@@ -0,0 +1,231 @@
+import { Injector } from '@angular/core';
+import { Subject } from 'rxjs';
+import { Duration, Event, EventsComponent } from './events.component';
+import { EventsService } from './events.service';
+
+describe('EventsComponent', () => {
+  let component: EventsComponent;
+  let injector: Injector;
+  let eventsService: TestEventsService;
+
+  beforeEach(() => {
+    injector = Injector.create({
+      providers: [
+        { provide: EventsComponent, deps: [EventsService] } ,
+        { provide: EventsService, useClass: TestEventsService, deps: [] },
+      ]
+    });
+    eventsService = injector.get(EventsService) as unknown as TestEventsService;
+    component = injector.get(EventsComponent) as unknown as EventsComponent;
+  });
+
+  it('should have no pastEvents when first created', () => {
+    expect(component.pastEvents).toBeUndefined();
+  });
+
+  it('should have no upcoming when first created', () => {
+    expect(component.upcomingEvents).toBeUndefined();
+  });
+
+  describe('ngOnInit()', () => {
+    beforeEach(() => {
+      jasmine.clock().install();
+      jasmine.clock().mockDate(new Date(2020, 5, 15, 23, 59, 59));
+      component.ngOnInit();
+    });
+
+    afterEach(() => jasmine.clock().uninstall());
+
+    it('should separate past and upcoming events', () => {
+      eventsService.events.next([
+        createMockEvent(
+            'Upcoming event 1',
+            {start: '2020-06-16', end: '2020-06-17'},
+            {start: '2020-06-18', end: '2020-06-18'}),
+        createMockEvent(
+            'Upcoming event 3',
+            {start: '2222-01-01', end: '2222-01-02'}),
+        createMockEvent(
+            'Past event 2',
+            {start: '2020-06-13', end: '2020-06-14'}),
+        createMockEvent(
+            'Upcoming event 2',
+            {start: '2020-06-17', end: '2020-06-18'},
+            {start: '2020-06-16', end: '2020-06-16'}),
+        createMockEvent(
+            'Past event 1',
+            {start: '2020-05-30', end: '2020-05-31'}),
+        createMockEvent(
+            'Past event 3',
+            {start: '2020-06-14', end: '2020-06-14'},
+            {start: '2020-06-16', end: '2020-06-17'}),
+      ]);
+
+      expect(component.pastEvents.map(evt => evt.name)).toEqual(jasmine.arrayWithExactContents(
+          ['Past event 1', 'Past event 2', 'Past event 3']));
+
+      expect(component.upcomingEvents.map(evt => evt.name)).toEqual(jasmine.arrayWithExactContents(
+          ['Upcoming event 1', 'Upcoming event 2', 'Upcoming event 3']));
+    });
+
+    it('should order past events in reverse chronological order (ignoring workshops dates)', () => {
+      eventsService.events.next([
+        createMockEvent(
+            'Past event 2',
+            {start: '1999-12-13', end: '1999-12-14'},
+            {start: '1999-12-11', end: '1999-12-11'}),
+        createMockEvent(
+            'Past event 4',
+            {start: '2020-01-16', end: '2020-01-17'},
+            {start: '2020-01-14', end: '2020-01-15'}),
+        createMockEvent(
+            'Past event 3',
+            {start: '2020-01-15', end: '2020-01-16'},
+            {start: '2020-01-17', end: '2020-01-18'}),
+        createMockEvent(
+            'Past event 1',
+            {start: '1999-12-12', end: '1999-12-15'}),
+      ]);
+
+      expect(component.pastEvents.map(evt => evt.name)).toEqual(
+          ['Past event 4', 'Past event 3', 'Past event 2', 'Past event 1']);
+    });
+
+    it('should order upcoming events in chronological order (ignoring workshops dates)', () => {
+      eventsService.events.next([
+        createMockEvent(
+            'Upcoming event 2',
+            {start: '2020-12-13', end: '2020-12-14'},
+            {start: '2020-12-11', end: '2020-12-11'}),
+        createMockEvent(
+            'Upcoming event 4',
+            {start: '2021-01-16', end: '2021-01-17'},
+            {start: '2021-01-14', end: '2021-01-15'}),
+        createMockEvent(
+            'Upcoming event 3',
+            {start: '2021-01-15', end: '2021-01-16'},
+            {start: '2021-01-17', end: '2021-01-18'}),
+        createMockEvent(
+            'Upcoming event 1',
+            {start: '2020-12-12', end: '2020-12-15'}),
+      ]);
+
+      expect(component.upcomingEvents.map(evt => evt.name)).toEqual(
+          ['Upcoming event 1', 'Upcoming event 2', 'Upcoming event 3', 'Upcoming event 4']);
+    });
+
+    it('should treat ongoing events as upcoming', () => {
+      eventsService.events.next([
+        createMockEvent(
+            'Ongoing event 1',
+            {start: '2020-06-14', end: '2020-06-16'}),
+        createMockEvent(
+            'Ongoing event 2',
+            {start: '2020-06-14', end: '2020-06-15'},
+            {start: '2020-06-13', end: '2020-06-13'}),
+      ]);
+
+      expect(component.pastEvents).toEqual([]);
+      expect(component.upcomingEvents.map(evt => evt.name)).toEqual(jasmine.arrayWithExactContents(
+          ['Ongoing event 1', 'Ongoing event 2']));
+    });
+  });
+
+  describe('getEventDates()', () => {
+    describe('(without workshops)', () => {
+      it('should correctly format the main event date', () => {
+        const testEvent = createMockEvent('Test', {start: '2020-06-20', end: '2020-06-20'});
+        expect(component.getEventDates(testEvent)).toBe('June 20, 2020');
+      });
+
+      it('should correctly format the main event date spanning mupliple days', () => {
+        const testEvent = createMockEvent('Test', {start: '2019-09-19', end: '2019-09-21'});
+        expect(component.getEventDates(testEvent)).toBe('September 19-21, 2019');
+      });
+
+      it('should correctly format the main event date spanning mupliple months', () => {
+        const testEvent = createMockEvent('Test', {start: '2019-10-30', end: '2019-11-01'});
+        expect(component.getEventDates(testEvent)).toBe('October 30 - November 1, 2019');
+      });
+    });
+
+    describe('(with workshops)', () => {
+      it('should correctly format event dates with workshops after main event', () => {
+        const testEvent = createMockEvent(
+            'Test',
+            {start: '2020-07-25', end: '2020-07-26'},
+            {start: '2020-07-27', end: '2020-07-27'});
+
+        expect(component.getEventDates(testEvent))
+            .toBe('July 25-26 (conference), July 27 (workshops), 2020');
+      });
+
+      it('should correctly format event dates with workshops before main event', () => {
+        const testEvent = createMockEvent(
+            'Test',
+            {start: '2019-10-07', end: '2019-10-07'},
+            {start: '2019-10-06', end: '2019-10-06'});
+
+        expect(component.getEventDates(testEvent))
+            .toBe('October 6 (workshops), October 7 (conference), 2019');
+      });
+
+      it('should correctly format event dates spanning multiple days', () => {
+        const testEvent = createMockEvent(
+            'Test',
+            {start: '2019-08-30', end: '2019-08-31'},
+            {start: '2019-08-28', end: '2019-08-29'});
+
+        expect(component.getEventDates(testEvent))
+            .toBe('August 28-29 (workshops), August 30-31 (conference), 2019');
+      });
+
+      it('should correctly format event dates with workshops on different month before the main event',
+        () => {
+          const testEvent = createMockEvent(
+              'Test',
+              {start: '2020-08-01', end: '2020-08-02'},
+              {start: '2020-07-30', end: '2020-07-31'});
+
+          expect(component.getEventDates(testEvent))
+              .toBe('July 30-31 (workshops), August 1-2 (conference), 2020');
+        });
+
+      it('should correctly format event dates with workshops on different month after the main event',
+        () => {
+          const testEvent = createMockEvent(
+              'Test',
+              {start: '2020-07-30', end: '2020-07-31'},
+              {start: '2020-08-01', end: '2020-08-02'});
+
+          expect(component.getEventDates(testEvent))
+              .toBe('July 30-31 (conference), August 1-2 (workshops), 2020');
+        });
+
+      it('should correctly format event dates spanning multiple months', () => {
+        const testEvent = createMockEvent(
+            'Test',
+            {start: '2020-07-31', end: '2020-08-01'},
+            {start: '2020-07-30', end: '2020-08-01'});
+
+        expect(component.getEventDates(testEvent))
+            .toBe('July 30 - August 1 (workshops), July 31 - August 1 (conference), 2020');
+      });
+    });
+  });
+
+  // Helpers
+  class TestEventsService {
+    events = new Subject<Event[]>();
+  }
+
+  function createMockEvent(name: string, date: Duration, workshopsDate?: Duration): Event {
+    return {
+      name,
+      location: '',
+      linkUrl: '',
+      date,
+      workshopsDate,
+    };
+  }
+});

aio/src/app/custom-elements/events/events.component.ts

@@ -0,0 +1,102 @@
+import { Component, OnInit } from '@angular/core';
+
+import { EventsService } from './events.service';
+
+const DAY = 24 * 60 * 60 * 1000;
+const MONTHS = [
+  'January',
+  'February',
+  'March',
+  'April',
+  'May',
+  'June',
+  'July',
+  'August',
+  'September',
+  'October',
+  'November',
+  'December',
+];
+
+export type date = string; // of the format `YYYY-MM-DD`.
+export interface Duration {
+  start: date;
+  end: date;
+}
+
+export interface Event {
+  name: string;
+  location: string;
+  linkUrl: string;
+  tooltip?: string;
+  date: Duration;
+  workshopsDate?: Duration;
+}
+
+@Component({
+  selector: 'aio-events',
+  templateUrl: 'events.component.html'
+})
+export class EventsComponent implements OnInit {
+
+  pastEvents: Event[];
+  upcomingEvents: Event[];
+
+  constructor(private eventsService: EventsService) { }
+
+  ngOnInit() {
+    this.eventsService.events.subscribe(events => {
+      this.pastEvents = events
+          .filter(event => new Date(event.date.end).getTime() < Date.now() - DAY)
+          .sort((l: Event, r: Event) => isBefore(l.date, r.date) ? 1 : -1);
+
+      this.upcomingEvents = events
+          .filter(event => new Date(event.date.end).getTime() >= Date.now() - DAY)
+          .sort((l: Event, r: Event) => isBefore(l.date, r.date) ? -1 : 1);
+    });
+  }
+
+  getEventDates(event: Event) {
+    let dateString;
+
+    // Check if there is a workshop
+    if (event.workshopsDate) {
+      const mainEventDateString = `${processDate(event.date)} (conference)`;
+      const workshopsDateString = `${processDate(event.workshopsDate)} (workshops)`;
+      const areWorkshopsBeforeEvent = isBefore(event.workshopsDate, event.date);
+
+      dateString = areWorkshopsBeforeEvent ?
+          `${workshopsDateString}, ${mainEventDateString}` :
+          `${mainEventDateString}, ${workshopsDateString}`;
+    } else {
+      // If no work shop date create conference date string
+      dateString = processDate(event.date);
+    }
+    dateString = `${dateString}, ${new Date(event.date.end).getFullYear()}`;
+    return dateString;
+  }
+}
+
+function processDate(dates: Duration) {
+  // Covert Date sting to date object for comparisons
+  const startDate = new Date(dates.start);
+  const endDate = new Date(dates.end);
+
+  // Create a date string in the start like January 31
+  let processedDate = `${MONTHS[startDate.getMonth()]} ${startDate.getDate()}`;
+
+  // If they are in different months add the string '- February 2' Making the final string January 31 - February 2
+  if (startDate.getMonth() !== endDate.getMonth()) {
+    processedDate = `${processedDate} - ${MONTHS[endDate.getMonth()]} ${endDate.getDate()}`;
+  } else if (startDate.getDate() !== endDate.getDate()) {
+    // If not add - date eg it will make // January 30-31
+    processedDate = `${processedDate}-${endDate.getDate()}`;
+  }
+
+  return processedDate;
+}
+
+function isBefore(duration1: Duration, duration2: Duration): boolean {
+  return (duration1.start < duration2.start) ||
+      (duration1.start === duration2.start && duration1.end < duration2.end);
+}

aio/src/app/custom-elements/events/events.module.ts

@@ -0,0 +1,15 @@
+import { NgModule, Type } from '@angular/core';
+import { CommonModule } from '@angular/common';
+import { EventsComponent } from './events.component';
+import { EventsService } from './events.service';
+import { WithCustomElementComponent } from '../element-registry';
+
+@NgModule({
+  imports: [ CommonModule ],
+  declarations: [ EventsComponent ],
+  entryComponents: [ EventsComponent ],
+  providers: [ EventsService]
+})
+export class EventsModule implements WithCustomElementComponent {
+  customElementComponent: Type<any> = EventsComponent;
+}

aio/src/app/custom-elements/events/events.service.spec.ts

@@ -0,0 +1,56 @@
+import { HttpClientTestingModule, HttpTestingController } from '@angular/common/http/testing';
+import { Injector } from '@angular/core';
+import { TestBed } from '@angular/core/testing';
+
+import { EventsService } from './events.service';
+import { Logger } from 'app/shared/logger.service';
+import { MockLogger } from 'testing/logger.service';
+
+describe('EventsService', () => {
+
+  let injector: Injector;
+  let eventsService: EventsService;
+  let httpMock: HttpTestingController;
+  let mockLogger: MockLogger;
+
+  beforeEach(() => {
+    injector = TestBed.configureTestingModule({
+      imports: [HttpClientTestingModule],
+      providers: [
+        EventsService,
+        { provide: Logger, useClass: MockLogger }
+      ]
+    });
+
+    eventsService = injector.get<EventsService>(EventsService);
+    mockLogger = injector.get(Logger) as any;
+    httpMock = injector.get(HttpTestingController);
+  });
+
+  afterEach(() => httpMock.verify());
+
+  it('should make a single connection to the server', () => {
+    eventsService.events.subscribe();
+    eventsService.events.subscribe();
+    httpMock.expectOne('generated/events.json');
+    expect().nothing();  // Prevent jasmine from complaining about no expectations.
+  });
+
+  it('should handle a failed request for `events.json`', () => {
+    const request = httpMock.expectOne('generated/events.json');
+    request.error(new ErrorEvent('404'));
+    expect(mockLogger.output.error).toEqual([
+      [jasmine.any(Error)]
+    ]);
+    expect(mockLogger.output.error[0][0].message).toMatch(/^generated\/events\.json request failed:/);
+  });
+
+  it('should return an empty array on a failed request for `events.json`', done => {
+    const request = httpMock.expectOne('generated/events.json');
+    request.error(new ErrorEvent('404'));
+    eventsService.events.subscribe(results => {
+      expect(results).toEqual([]);
+      done();
+    });
+  });
+});

aio/src/app/custom-elements/events/events.service.ts

@@ -0,0 +1,32 @@
+import { Injectable } from '@angular/core';
+import { HttpClient } from '@angular/common/http';
+
+import { ConnectableObservable, Observable, of } from 'rxjs';
+import { catchError, publishLast } from 'rxjs/operators';
+
+import { Event } from './events.component';
+import { CONTENT_URL_PREFIX } from 'app/documents/document.service';
+import { Logger } from 'app/shared/logger.service';
+
+const eventsPath = CONTENT_URL_PREFIX + 'events.json';
+
+@Injectable()
+export class EventsService {
+  events: Observable<Event[]>;
+
+  constructor(private http: HttpClient, private logger: Logger) {
+    this.events = this.getEvents();
+  }
+
+  private getEvents() {
+    const events = this.http.get<any>(eventsPath).pipe(
+      catchError(error => {
+        this.logger.error(new Error(`${eventsPath} request failed: ${error.message}`));
+        return of([]);
+      }),
+      publishLast()
+    );
+    (events as ConnectableObservable<Event[]>).connect();
+    return events;
+  }
+}

aio/src/styles/2-modules/_modules-dir.scss

@@ -25,7 +25,6 @@
    @import 'progress-bar';
    @import 'presskit';
    @import 'resources';
-   @import 'scrollbar';
    @import 'search-results';
    @import 'select-menu';
    @import 'table';

aio/src/styles/2-modules/_scrollbar.scss

@@ -1,27 +0,0 @@
-body::-webkit-scrollbar, mat-sidenav.sidenav::-webkit-scrollbar, .mat-sidenav-content::-webkit-scrollbar {
-  height: 6px;
-  width: 6px;
-}
-
-body::-webkit-scrollbar-track, mat-sidenav.sidenav::-webkit-scrollbar-track, .mat-sidenav-content::-webkit-scrollbar-track {
-  -webkit-box-shadow: inset 0 0 6px rgba(0,0,0,0.3);
-}
-
-body::-webkit-scrollbar-thumb, mat-sidenav.sidenav::-webkit-scrollbar-thumb, .mat-sidenav-content::-webkit-scrollbar-thumb {
-  background-color: $mediumgray;
-  outline: 1px solid $darkgray;
-}
-
-.search-results::-webkit-scrollbar, .toc-container::-webkit-scrollbar {
-  height: 4px;
-  width: 4px;
-}
-
-.search-results::-webkit-scrollbar-track, .toc-container::-webkit-scrollbar-track {
-  -webkit-box-shadow: inset 0 0 6px rgba(0,0,0,0.3);
-}
-
-.search-results::-webkit-scrollbar-thumb, .toc-container::-webkit-scrollbar-thumb {
-  background-color: $mediumgray;
-  outline: 1px solid slategrey;
-}

aio/tools/transforms/angular-base-package/processors/createSitemap.js

@@ -5,6 +5,7 @@ module.exports = function createSitemap() {
       'contributors-json',
       'navigation-json',
       'resources-json',
+      'events-json'
     ],
     ignoredPaths: [
       'file-not-found',

aio/tools/transforms/angular-content-package/index.js

@@ -82,6 +82,11 @@ module.exports = new Package('angular-content', [basePackage, contentPackage])
         include: CONTENTS_PATH + '/marketing/resources.json',
         fileReader: 'jsonFileReader'
       },
+      {
+        basePath: CONTENTS_PATH,
+        include: CONTENTS_PATH + '/marketing/events.json',
+        fileReader: 'jsonFileReader'
+      },
     ]);
 
     collectExamples.exampleFolders.push('examples');
@@ -110,7 +115,8 @@ module.exports = new Package('angular-content', [basePackage, contentPackage])
       {docTypes: ['navigation-json'], pathTemplate: '${id}', outputPathTemplate: '../${id}.json'},
       {docTypes: ['contributors-json'], pathTemplate: '${id}', outputPathTemplate: '../${id}.json'},
       {docTypes: ['announcements-json'], pathTemplate: '${id}', outputPathTemplate: '../${id}.json'},
-      {docTypes: ['resources-json'], pathTemplate: '${id}', outputPathTemplate: '../${id}.json'}
+      {docTypes: ['resources-json'], pathTemplate: '${id}', outputPathTemplate: '../${id}.json'},
+      {docTypes: ['events-json'], pathTemplate: '${id}', outputPathTemplate: '../${id}.json'}
     ]);
   })
 

aio/tools/transforms/templates/api/lib/memberHelpers.html

@@ -3,7 +3,7 @@
 
 {%- macro renderHeritage(exportDoc) -%}
   {%- if exportDoc.extendsClauses.length %} extends {% for clause in exportDoc.extendsClauses -%}
-  <a class="code-anchor" href="{$ clause.doc.path $}">{$ clause.text $}</a>{% if not loop.last %}, {% endif -%}
+  {% if clause.doc.path %}<a class="code-anchor" href="{$ clause.doc.path $}">{$ clause.text $}</a>{% else %}{$ clause.text $}{% endif %}{% if not loop.last %}, {% endif -%}
   {% endfor %}{% endif %}
   {%- if exportDoc.implementsClauses.length %} implements {% for clause in exportDoc.implementsClauses -%}
   <a class="code-anchor" href="{$ clause.doc.path $}">{$ clause.text $}</a>{% if not loop.last %}, {% endif -%}

dev-infra/benchmark/driver-utilities/e2e_util.ts

@@ -13,7 +13,7 @@ import * as webdriver from 'selenium-webdriver';
 declare var expect: any;
 
 export function openBrowser(config: {
-  url: string,
+  url?: string,
   params?: {name: string, value: any}[],
   ignoreBrowserSynchronization?: boolean
 }) {

dev-infra/benchmark/driver-utilities/perf_util.ts

@@ -23,27 +23,34 @@ const globalOptions = {
 
 const runner = createBenchpressRunner();
 
-export async function runBenchmark(config: {
+export async function runBenchmark({
+  id,
+  url = '',
+  params = [],
+  ignoreBrowserSynchronization = true,
+  microMetrics,
+  work,
+  prepare,
+  setup,
+}: {
   id: string,
-  url: string,
-  params: {name: string, value: any}[],
+  url?: string,
+  params?: {name: string, value: any}[],
   ignoreBrowserSynchronization?: boolean,
   microMetrics?: {[key: string]: string},
-  work?: () => void,
-  prepare?: () => void,
-  setup?: () => void
+  work?: (() => void)|(() => Promise<unknown>),
+  prepare?: (() => void)|(() => Promise<unknown>),
+  setup?: (() => void)|(() => Promise<unknown>),
 }): Promise<any> {
-  openBrowser(config);
-  if (config.setup) {
-    await config.setup();
+  openBrowser({url, params, ignoreBrowserSynchronization});
+  if (setup) {
+    await setup();
   }
-  const description: {[key: string]: any} = {};
-  config.params.forEach((param) => description[param.name] = param.value);
   return runner.sample({
-    id: config.id,
-    execute: config.work,
-    prepare: config.prepare,
-    microMetrics: config.microMetrics,
+    id,
+    execute: work,
+    prepare,
+    microMetrics,
     providers: [{provide: Options.SAMPLE_DESCRIPTION, useValue: {}}]
   });
 }

dev-infra/caretaker/BUILD.bazel

@@ -2,25 +2,20 @@ load("@npm_bazel_typescript//:index.bzl", "ts_library")
 
 ts_library(
     name = "caretaker",
-    srcs = [
-        "cli.ts",
-    ],
+    srcs = glob([
+        "**/*.ts",
+    ]),
     module_name = "@angular/dev-infra-private/caretaker",
     visibility = ["//dev-infra:__subpackages__"],
     deps = [
-        "//dev-infra/caretaker/check",
+        "//dev-infra/utils",
+        "@npm//@types/node",
+        "@npm//@types/node-fetch",
         "@npm//@types/yargs",
+        "@npm//multimatch",
+        "@npm//node-fetch",
+        "@npm//typed-graphqlify",
+        "@npm//yaml",
         "@npm//yargs",
     ],
 )
-
-ts_library(
-    name = "config",
-    srcs = [
-        "config.ts",
-    ],
-    visibility = ["//dev-infra:__subpackages__"],
-    deps = [
-        "//dev-infra/utils",
-    ],
-)

dev-infra/caretaker/check/BUILD.bazel

@@ -1,21 +0,0 @@
-load("@npm_bazel_typescript//:index.bzl", "ts_library")
-
-ts_library(
-    name = "check",
-    srcs = glob(["*.ts"]),
-    module_name = "@angular/dev-infra-private/caretaker/service-statuses",
-    visibility = ["//dev-infra:__subpackages__"],
-    deps = [
-        "//dev-infra/caretaker:config",
-        "//dev-infra/utils",
-        "@npm//@types/fs-extra",
-        "@npm//@types/node",
-        "@npm//@types/node-fetch",
-        "@npm//@types/yargs",
-        "@npm//multimatch",
-        "@npm//node-fetch",
-        "@npm//typed-graphqlify",
-        "@npm//yaml",
-        "@npm//yargs",
-    ],
-)

dev-infra/caretaker/check/check.ts

@@ -9,6 +9,7 @@
 import {GitClient} from '../../utils/git';
 import {getCaretakerConfig} from '../config';
 
+import {printCiStatus} from './ci';
 import {printG3Comparison} from './g3';
 import {printGithubTasks} from './github';
 import {printServiceStatuses} from './services';
@@ -21,7 +22,9 @@ export async function checkServiceStatuses(githubToken: string) {
   /** The GitClient for interacting with git and Github. */
   const git = new GitClient(githubToken, config);
 
+  // TODO(josephperrott): Allow these checks to be loaded in parallel.
   await printServiceStatuses();
   await printGithubTasks(git, config.caretaker);
   await printG3Comparison(git);
+  await printCiStatus(git);
 }

dev-infra/caretaker/check/ci.ts

@@ -0,0 +1,59 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+import fetch from 'node-fetch';
+
+import {bold, green, info, red} from '../../utils/console';
+import {GitClient} from '../../utils/git';
+
+
+/** The results of checking the status of CI.  */
+interface StatusCheckResult {
+  status: 'success'|'failed'|'canceled'|'infrastructure_fail'|'timedout'|'failed'|'no_tests';
+  timestamp: Date;
+  buildUrl: string;
+}
+
+/** Retrieve and log status of CI for the project. */
+export async function printCiStatus(git: GitClient) {
+  info.group(bold(`CI`));
+  // TODO(josephperrott): Expand list of branches checked to all active branches.
+  await printStatus(git, 'master');
+  info.groupEnd();
+  info();
+}
+
+/** Log the status of CI for a given branch to the console. */
+async function printStatus(git: GitClient, branch: string) {
+  const result = await getStatusOfBranch(git, branch);
+  const branchName = branch.padEnd(10);
+  if (result === null) {
+    info(`${branchName} was not found on CircleCI`);
+  } else if (result.status === 'success') {
+    info(`${branchName} ✅`);
+  } else {
+    info(`${branchName} ❌ (Ran at: ${result.timestamp.toLocaleString()})`);
+  }
+}
+
+/** Get the CI status of a given branch from CircleCI. */
+async function getStatusOfBranch(git: GitClient, branch: string): Promise<StatusCheckResult|null> {
+  const {owner, name} = git.remoteConfig;
+  const url = `https://circleci.com/api/v1.1/project/gh/${owner}/${name}/tree/${
+      branch}?limit=1&filter=completed&shallow=true`;
+  const result = (await fetch(url).then(result => result.json()))?.[0];
+
+  if (result) {
+    return {
+      status: result.outcome,
+      timestamp: new Date(result.stop_time),
+      buildUrl: result.build_url
+    };
+  }
+  return null;
+}

dev-infra/caretaker/check/g3.ts

@@ -6,7 +6,7 @@
  * found in the LICENSE file at https://angular.io/license
  */
 
-import {existsSync, readFileSync} from 'fs-extra';
+import {existsSync, readFileSync} from 'fs';
 import * as multimatch from 'multimatch';
 import {join} from 'path';
 import {parse as parseYaml} from 'yaml';

dev-infra/caretaker/check/github.ts

@@ -13,15 +13,9 @@ import {GitClient} from '../../utils/git';
 import {CaretakerConfig} from '../config';
 
 
-interface GithubInfoQuery {
-  [key: string]: {
-    issueCount: number,
-  };
-}
-
 /** Retrieve the number of matching issues for each github query. */
-export async function printGithubTasks(git: GitClient, config: CaretakerConfig) {
-  if (!config.githubQueries?.length) {
+export async function printGithubTasks(git: GitClient, config?: CaretakerConfig) {
+  if (!config?.githubQueries?.length) {
     debug('No github queries defined in the configuration, skipping.');
     return;
   }

dev-infra/commit-message/BUILD.bazel

@@ -3,18 +3,10 @@ load("@npm_bazel_typescript//:index.bzl", "ts_library")
 
 ts_library(
     name = "commit-message",
-    srcs = [
-        "builder.ts",
-        "cli.ts",
-        "commit-message-draft.ts",
-        "config.ts",
-        "parse.ts",
-        "restore-commit-message.ts",
-        "validate.ts",
-        "validate-file.ts",
-        "validate-range.ts",
-        "wizard.ts",
-    ],
+    srcs = glob(
+        ["**/*.ts"],
+        exclude = ["**/*.spec.ts"],
+    ),
     module_name = "@angular/dev-infra-private/commit-message",
     visibility = ["//dev-infra:__subpackages__"],
     deps = [
@@ -32,11 +24,7 @@ ts_library(
 ts_library(
     name = "test_lib",
     testonly = True,
-    srcs = [
-        "builder.spec.ts",
-        "parse.spec.ts",
-        "validate.spec.ts",
-    ],
+    srcs = glob(["**/*.spec.ts"]),
     deps = [
         ":commit-message",
         "//dev-infra/utils",

dev-infra/commit-message/cli.ts

@@ -7,104 +7,19 @@
  */
 import * as yargs from 'yargs';
 
-import {info} from '../utils/console';
-
-import {restoreCommitMessage} from './restore-commit-message';
-import {validateFile} from './validate-file';
-import {validateCommitRange} from './validate-range';
-import {runWizard} from './wizard';
+import {RestoreCommitMessageModule} from './restore-commit-message/cli';
+import {ValidateFileModule} from './validate-file/cli';
+import {ValidateRangeModule} from './validate-range/cli';
+import {WizardModule} from './wizard/cli';
 
 /** Build the parser for the commit-message commands. */
 export function buildCommitMessageParser(localYargs: yargs.Argv) {
   return localYargs.help()
       .strict()
-      .command(
-          'restore-commit-message-draft', false,
-          args => {
-            return args.option('file-env-variable', {
-              type: 'string',
-              array: true,
-              conflicts: ['file'],
-              required: true,
-              description:
-                  'The key for the environment variable which holds the arguments for the\n' +
-                  'prepare-commit-msg hook as described here:\n' +
-                  'https://git-scm.com/docs/githooks#_prepare_commit_msg',
-              coerce: arg => {
-                const [file, source] = (process.env[arg] || '').split(' ');
-                if (!file) {
-                  throw new Error(`Provided environment variable "${arg}" was not found.`);
-                }
-                return [file, source];
-              },
-            });
-          },
-          args => {
-            restoreCommitMessage(args['file-env-variable'][0], args['file-env-variable'][1] as any);
-          })
-      .command(
-          'wizard <filePath> [source] [commitSha]', '', ((args: any) => {
-            return args
-                .positional(
-                    'filePath',
-                    {description: 'The file path to write the generated commit message into'})
-                .positional('source', {
-                  choices: ['message', 'template', 'merge', 'squash', 'commit'],
-                  description: 'The source of the commit message as described here: ' +
-                      'https://git-scm.com/docs/githooks#_prepare_commit_msg'
-                })
-                .positional(
-                    'commitSha', {description: 'The commit sha if source is set to `commit`'});
-          }),
-          async (args: any) => {
-            await runWizard(args);
-          })
-      .command(
-          'pre-commit-validate', 'Validate the most recent commit message', {
-            'file': {
-              type: 'string',
-              conflicts: ['file-env-variable'],
-              description: 'The path of the commit message file.',
-            },
-            'file-env-variable': {
-              type: 'string',
-              conflicts: ['file'],
-              description:
-                  'The key of the environment variable for the path of the commit message file.',
-              coerce: arg => {
-                const file = process.env[arg];
-                if (!file) {
-                  throw new Error(`Provided environment variable "${arg}" was not found.`);
-                }
-                return file;
-              },
-            }
-          },
-          args => {
-            const file = args.file || args['file-env-variable'] || '.git/COMMIT_EDITMSG';
-            validateFile(file);
-          })
-      .command(
-          'validate-range', 'Validate a range of commit messages', {
-            'range': {
-              description: 'The range of commits to check, e.g. --range abc123..xyz456',
-              demandOption: '  A range must be provided, e.g. --range abc123..xyz456',
-              type: 'string',
-              requiresArg: true,
-            },
-          },
-          argv => {
-            // If on CI, and not pull request number is provided, assume the branch
-            // being run on is an upstream branch.
-            if (process.env['CI'] && process.env['CI_PULL_REQUEST'] === 'false') {
-              info(`Since valid commit messages are enforced by PR linting on CI, we do not`);
-              info(`need to validate commit messages on CI runs on upstream branches.`);
-              info();
-              info(`Skipping check of provided commit range`);
-              return;
-            }
-            validateCommitRange(argv.range);
-          });
+      .command(RestoreCommitMessageModule)
+      .command(WizardModule)
+      .command(ValidateFileModule)
+      .command(ValidateRangeModule);
 }
 
 if (require.main == module) {

dev-infra/commit-message/commit-message-source.ts

@@ -0,0 +1,13 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+/**
+ * The source triggering the git commit message creation.
+ * As described in: https://git-scm.com/docs/githooks#_prepare_commit_msg
+ */
+export type CommitMsgSource = 'message'|'template'|'merge'|'squash'|'commit';

dev-infra/commit-message/config.ts

@@ -8,6 +8,7 @@
 
 import {assertNoErrors, getConfig, NgDevConfig} from '../utils/config';
 
+/** Configuration for commit-message comands. */
 export interface CommitMessageConfig {
   maxLineLength: number;
   minBodyLength: number;

dev-infra/commit-message/restore-commit-message/cli.ts

@@ -0,0 +1,51 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+import {Arguments, Argv, CommandModule} from 'yargs';
+
+import {CommitMsgSource} from '../commit-message-source';
+
+import {restoreCommitMessage} from './restore-commit-message';
+
+export interface RestoreCommitMessageOptions {
+  fileEnvVariable: string[];
+}
+
+/** Builds the command. */
+function builder(yargs: Argv) {
+  return yargs.option('file-env-variable' as 'fileEnvVariable', {
+    type: 'string',
+    array: true,
+    demandOption: true,
+    description: 'The key for the environment variable which holds the arguments for the\n' +
+        'prepare-commit-msg hook as described here:\n' +
+        'https://git-scm.com/docs/githooks#_prepare_commit_msg',
+    coerce: arg => {
+      const [file, source] = (process.env[arg] || '').split(' ');
+      if (!file) {
+        throw new Error(`Provided environment variable "${arg}" was not found.`);
+      }
+      return [file, source];
+    },
+  });
+}
+
+/** Handles the command. */
+async function handler({fileEnvVariable}: Arguments<RestoreCommitMessageOptions>) {
+  restoreCommitMessage(fileEnvVariable[0], fileEnvVariable[1] as CommitMsgSource);
+}
+
+/** yargs command module describing the command.  */
+export const RestoreCommitMessageModule: CommandModule<{}, RestoreCommitMessageOptions> = {
+  handler,
+  builder,
+  command: 'restore-commit-message-draft',
+  // Description: Restore a commit message draft if one has been saved from a failed commit attempt.
+  // No describe is defiend to hide the command from the --help.
+  describe: false,
+};

dev-infra/commit-message/restore-commit-message/restore-commit-message.ts

@@ -8,9 +8,10 @@
 
 import {writeFileSync} from 'fs';
 
-import {debug, log} from '../utils/console';
+import {debug, log} from '../../utils/console';
 
-import {loadCommitMessageDraft} from './commit-message-draft';
+import {loadCommitMessageDraft} from '../commit-message-draft';
+import {CommitMsgSource} from '../commit-message-source';
 
 /**
  * Restore the commit message draft to the git to be used as the default commit message.
@@ -18,8 +19,7 @@ import {loadCommitMessageDraft} from './commit-message-draft';
  * The source provided may be one of the sources described in
  *   https://git-scm.com/docs/githooks#_prepare_commit_msg
  */
-export function restoreCommitMessage(
-    filePath: string, source?: 'message'|'template'|'squash'|'commit') {
+export function restoreCommitMessage(filePath: string, source?: CommitMsgSource) {
   if (!!source) {
     log('Skipping commit message restoration attempt');
     if (source === 'message') {

dev-infra/commit-message/validate-file.ts

@@ -1,30 +0,0 @@
-/**
- * @license
- * Copyright Google LLC All Rights Reserved.
- *
- * Use of this source code is governed by an MIT-style license that can be
- * found in the LICENSE file at https://angular.io/license
- */
-import {readFileSync} from 'fs';
-import {resolve} from 'path';
-
-import {getRepoBaseDir} from '../utils/config';
-import {info} from '../utils/console';
-
-import {deleteCommitMessageDraft, saveCommitMessageDraft} from './commit-message-draft';
-import {validateCommitMessage} from './validate';
-
-/** Validate commit message at the provided file path. */
-export function validateFile(filePath: string) {
-  const commitMessage = readFileSync(resolve(getRepoBaseDir(), filePath), 'utf8');
-  if (validateCommitMessage(commitMessage)) {
-    info('√  Valid commit message');
-    deleteCommitMessageDraft(filePath);
-    return;
-  }
-  // On all invalid commit messages, the commit message should be saved as a draft to be
-  // restored on the next commit attempt.
-  saveCommitMessageDraft(filePath, commitMessage);
-  // If the validation did not return true, exit as a failure.
-  process.exit(1);
-}

dev-infra/commit-message/validate-file/cli.ts

@@ -0,0 +1,62 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+import {Arguments, Argv, CommandModule} from 'yargs';
+
+import {getUserConfig} from '../../utils/config';
+
+import {validateFile} from './validate-file';
+
+
+export interface ValidateFileOptions {
+  file?: string;
+  fileEnvVariable?: string;
+  error: boolean;
+}
+
+/** Builds the command. */
+function builder(yargs: Argv) {
+  return yargs
+      .option('file', {
+        type: 'string',
+        conflicts: ['file-env-variable'],
+        description: 'The path of the commit message file.',
+      })
+      .option('file-env-variable' as 'fileEnvVariable', {
+        type: 'string',
+        conflicts: ['file'],
+        description: 'The key of the environment variable for the path of the commit message file.',
+        coerce: (arg: string) => {
+          const file = process.env[arg];
+          if (!file) {
+            throw new Error(`Provided environment variable "${arg}" was not found.`);
+          }
+          return file;
+        },
+      })
+      .option('error', {
+        type: 'boolean',
+        description:
+            'Whether invalid commit messages should be treated as failures rather than a warning',
+        default: !!getUserConfig().commitMessage?.errorOnInvalidMessage || !!process.env['CI']
+      });
+}
+
+/** Handles the command. */
+async function handler({error, file, fileEnvVariable}: Arguments<ValidateFileOptions>) {
+  const filePath = file || fileEnvVariable || '.git/COMMIT_EDITMSG';
+  validateFile(filePath, error);
+}
+
+/** yargs command module describing the command.  */
+export const ValidateFileModule: CommandModule<{}, ValidateFileOptions> = {
+  handler,
+  builder,
+  command: 'pre-commit-validate',
+  describe: 'Validate the most recent commit message',
+};

dev-infra/commit-message/validate-file/validate-file.ts

@@ -0,0 +1,47 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+import {readFileSync} from 'fs';
+import {resolve} from 'path';
+
+import {getRepoBaseDir} from '../../utils/config';
+import {error, green, info, log, red, yellow} from '../../utils/console';
+
+import {deleteCommitMessageDraft, saveCommitMessageDraft} from '../commit-message-draft';
+import {printValidationErrors, validateCommitMessage} from '../validate';
+
+/** Validate commit message at the provided file path. */
+export function validateFile(filePath: string, isErrorMode: boolean) {
+  const commitMessage = readFileSync(resolve(getRepoBaseDir(), filePath), 'utf8');
+  const {valid, errors} = validateCommitMessage(commitMessage);
+  if (valid) {
+    info(`${green('√')}  Valid commit message`);
+    deleteCommitMessageDraft(filePath);
+    process.exitCode = 0;
+    return;
+  }
+
+  /** Function used to print to the console log. */
+  let printFn = isErrorMode ? error : log;
+
+  printFn(`${isErrorMode ? red('✘') : yellow('!')}  Invalid commit message`);
+  printValidationErrors(errors, printFn);
+  if (isErrorMode) {
+    printFn(red('Aborting commit attempt due to invalid commit message.'));
+    printFn(
+        red('Commit message aborted as failure rather than warning due to local configuration.'));
+  } else {
+    printFn(yellow('Before this commit can be merged into the upstream repository, it must be'));
+    printFn(yellow('amended to follow commit message guidelines.'));
+  }
+
+  // On all invalid commit messages, the commit message should be saved as a draft to be
+  // restored on the next commit attempt.
+  saveCommitMessageDraft(filePath, commitMessage);
+  // Set the correct exit code based on if invalid commit message is an error.
+  process.exitCode = isErrorMode ? 1 : 0;
+}

dev-infra/commit-message/validate-range/cli.ts

@@ -0,0 +1,50 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+import {Arguments, Argv, CommandModule} from 'yargs';
+
+import {info} from '../../utils/console';
+
+import {validateCommitRange} from './validate-range';
+
+
+export interface ValidateRangeOptions {
+  range: string;
+}
+
+/** Builds the command. */
+function builder(yargs: Argv) {
+  return yargs.option('range', {
+    description: 'The range of commits to check, e.g. --range abc123..xyz456',
+    demandOption: '  A range must be provided, e.g. --range abc123..xyz456',
+    type: 'string',
+    requiresArg: true,
+  });
+}
+
+/** Handles the command. */
+async function handler({range}: Arguments<ValidateRangeOptions>) {
+  // If on CI, and no pull request number is provided, assume the branch
+  // being run on is an upstream branch.
+  if (process.env['CI'] && process.env['CI_PULL_REQUEST'] === 'false') {
+    info(`Since valid commit messages are enforced by PR linting on CI, we do not`);
+    info(`need to validate commit messages on CI runs on upstream branches.`);
+    info();
+    info(`Skipping check of provided commit range`);
+    return;
+  }
+  validateCommitRange(range);
+}
+
+/** yargs command module describing the command.  */
+export const ValidateRangeModule: CommandModule<{}, ValidateRangeOptions> = {
+  handler,
+  builder,
+  command: 'validate-range',
+  describe: 'Validate a range of commit messages',
+};

dev-infra/commit-message/validate-range/validate-range.ts

@@ -5,11 +5,11 @@
  * Use of this source code is governed by an MIT-style license that can be
  * found in the LICENSE file at https://angular.io/license
  */
-import {info} from '../utils/console';
-import {exec} from '../utils/shelljs';
+import {error, info} from '../../utils/console';
+import {exec} from '../../utils/shelljs';
 
-import {parseCommitMessage} from './parse';
-import {validateCommitMessage, ValidateCommitMessageOptions} from './validate';
+import {parseCommitMessage} from '../parse';
+import {printValidationErrors, validateCommitMessage, ValidateCommitMessageOptions} from '../validate';
 
 // Whether the provided commit is a fixup commit.
 const isNonFixup = (m: string) => !parseCommitMessage(m).isFixup;
@@ -19,11 +19,20 @@ const extractCommitHeader = (m: string) => parseCommitMessage(m).header;
 
 /** Validate all commits in a provided git commit range. */
 export function validateCommitRange(range: string) {
-  // A random value is used as a string to allow for a definite split point in the git log result.
+  /**
+   * A random value is used as a string to allow for a definite split point in the git log result.
+   */
   const randomValueSeparator = `${Math.random()}`;
-  // Custom git log format that provides the commit header and body, separated as expected with
-  // the custom separator as the trailing value.
+  /**
+   * Custom git log format that provides the commit header and body, separated as expected with the
+   * custom separator as the trailing value.
+   */
   const gitLogFormat = `%s%n%n%b${randomValueSeparator}`;
+  /**
+   * A list of tuples containing a commit header string and the list of error messages for the
+   * commit.
+   */
+  const errors: [commitHeader: string, errors: string[]][] = [];
 
   // Retrieve the commits in the provided range.
   const result = exec(`git log --reverse --format=${gitLogFormat} ${range}`);
@@ -45,12 +54,22 @@ export function validateCommitRange(range: string) {
           undefined :
           commits.slice(0, i).filter(isNonFixup).map(extractCommitHeader)
     };
-    return validateCommitMessage(m, options);
+    const {valid, errors: localErrors, commit} = validateCommitMessage(m, options);
+    if (localErrors.length) {
+      errors.push([commit.header, localErrors]);
+    }
+    return valid;
   });
 
   if (allCommitsInRangeValid) {
     info('√  All commit messages in range valid.');
   } else {
+    error('✘  Invalid commit message');
+    errors.forEach(([header, validationErrors]) => {
+      error.group(header);
+      printValidationErrors(validationErrors);
+      error.groupEnd();
+    });
     // Exit with a non-zero exit code if invalid commit messages have
     // been discovered.
     process.exit(1);

dev-infra/commit-message/validate.spec.ts

@@ -8,7 +8,7 @@
 
 // Imports
 import * as validateConfig from './config';
-import {validateCommitMessage} from './validate';
+import {validateCommitMessage, ValidateCommitMessageResult} from './validate';
 
 type CommitMessageConfig = validateConfig.CommitMessageConfig;
 
@@ -31,44 +31,35 @@ const SCOPES = config.commitMessage.scopes.join(', ');
 const INVALID = false;
 const VALID = true;
 
+function expectValidationResult(
+    validationResult: ValidateCommitMessageResult, valid: boolean, errors: string[] = []) {
+  expect(validationResult).toEqual(jasmine.objectContaining({valid, errors}));
+}
+
 // TODO(josephperrott): Clean up tests to test script rather than for
 // specific commit messages we want to use.
 describe('validate-commit-message.js', () => {
-  let lastError: string = '';
-
   beforeEach(() => {
-    lastError = '';
-
-    spyOn(console, 'error').and.callFake((msg: string) => lastError = msg);
     spyOn(validateConfig, 'getCommitMessageConfig')
         .and.returnValue(config as ReturnType<typeof validateConfig.getCommitMessageConfig>);
   });
 
   describe('validateMessage()', () => {
     it('should be valid', () => {
-      expect(validateCommitMessage('feat(packaging): something')).toBe(VALID);
-      expect(lastError).toBe('');
-
-      expect(validateCommitMessage('fix(packaging): something')).toBe(VALID);
-      expect(lastError).toBe('');
-
-      expect(validateCommitMessage('fixup! fix(packaging): something')).toBe(VALID);
-      expect(lastError).toBe('');
-
-      expect(validateCommitMessage('squash! fix(packaging): something')).toBe(VALID);
-      expect(lastError).toBe('');
-
-      expect(validateCommitMessage('Revert: "fix(packaging): something"')).toBe(VALID);
-      expect(lastError).toBe('');
+      expectValidationResult(validateCommitMessage('feat(packaging): something'), VALID);
+      expectValidationResult(validateCommitMessage('fix(packaging): something'), VALID);
+      expectValidationResult(validateCommitMessage('fixup! fix(packaging): something'), VALID);
+      expectValidationResult(validateCommitMessage('squash! fix(packaging): something'), VALID);
+      expectValidationResult(validateCommitMessage('Revert: "fix(packaging): something"'), VALID);
     });
 
     it('should validate max length', () => {
       const msg =
           'fix(compiler): something super mega extra giga tera long, maybe even longer and longer and longer and longer and longer and longer...';
 
-      expect(validateCommitMessage(msg)).toBe(INVALID);
-      expect(lastError).toContain(`The commit message header is longer than ${
-          config.commitMessage.maxLineLength} characters`);
+      expectValidationResult(validateCommitMessage(msg), INVALID, [
+        `The commit message header is longer than ${config.commitMessage.maxLineLength} characters`
+      ]);
     });
 
     it('should skip max length limit for URLs', () => {
@@ -77,49 +68,56 @@ describe('validate-commit-message.js', () => {
           'limit. For more details see the following super long URL:\n\n' +
           'https://github.com/angular/components/commit/e2ace018ddfad10608e0e32932c43dcfef4095d7#diff-9879d6db96fd29134fc802214163b95a';
 
-      expect(validateCommitMessage(msg)).toBe(VALID);
+      expectValidationResult(validateCommitMessage(msg), VALID);
     });
 
     it('should validate "<type>(<scope>): <subject>" format', () => {
       const msg = 'not correct format';
 
-      expect(validateCommitMessage(msg)).toBe(INVALID);
-      expect(lastError).toContain(`The commit message header does not match the expected format.`);
+      expectValidationResult(
+          validateCommitMessage(msg), INVALID,
+          [`The commit message header does not match the expected format.`]);
     });
 
     it('should fail when type is invalid', () => {
       const msg = 'weird(core): something';
 
-      expect(validateCommitMessage(msg)).toBe(INVALID);
-      expect(lastError).toContain(`'weird' is not an allowed type.\n => TYPES: ${TYPES}`);
+      expectValidationResult(
+          validateCommitMessage(msg), INVALID,
+          [`'weird' is not an allowed type.\n => TYPES: ${TYPES}`]);
     });
 
     it('should fail when scope is invalid', () => {
       const errorMessageFor = (scope: string, header: string) =>
           `'${scope}' is not an allowed scope.\n => SCOPES: ${SCOPES}`;
 
-      expect(validateCommitMessage('fix(Compiler): something')).toBe(INVALID);
-      expect(lastError).toContain(errorMessageFor('Compiler', 'fix(Compiler): something'));
+      expectValidationResult(
+          validateCommitMessage('fix(Compiler): something'), INVALID,
+          [errorMessageFor('Compiler', 'fix(Compiler): something')]);
 
-      expect(validateCommitMessage('feat(bah): something')).toBe(INVALID);
-      expect(lastError).toContain(errorMessageFor('bah', 'feat(bah): something'));
+      expectValidationResult(
+          validateCommitMessage('feat(bah): something'), INVALID,
+          [errorMessageFor('bah', 'feat(bah): something')]);
 
-      expect(validateCommitMessage('fix(webworker): something')).toBe(INVALID);
-      expect(lastError).toContain(errorMessageFor('webworker', 'fix(webworker): something'));
+      expectValidationResult(
+          validateCommitMessage('fix(webworker): something'), INVALID,
+          [errorMessageFor('webworker', 'fix(webworker): something')]);
 
-      expect(validateCommitMessage('refactor(security): something')).toBe(INVALID);
-      expect(lastError).toContain(errorMessageFor('security', 'refactor(security): something'));
+      expectValidationResult(
+          validateCommitMessage('refactor(security): something'), INVALID,
+          [errorMessageFor('security', 'refactor(security): something')]);
 
-      expect(validateCommitMessage('refactor(docs): something')).toBe(INVALID);
-      expect(lastError).toContain(errorMessageFor('docs', 'refactor(docs): something'));
+      expectValidationResult(
+          validateCommitMessage('refactor(docs): something'), INVALID,
+          [errorMessageFor('docs', 'refactor(docs): something')]);
 
-      expect(validateCommitMessage('feat(angular): something')).toBe(INVALID);
-      expect(lastError).toContain(errorMessageFor('angular', 'feat(angular): something'));
+      expectValidationResult(
+          validateCommitMessage('feat(angular): something'), INVALID,
+          [errorMessageFor('angular', 'feat(angular): something')]);
     });
 
     it('should allow empty scope', () => {
-      expect(validateCommitMessage('build: blablabla')).toBe(VALID);
-      expect(lastError).toBe('');
+      expectValidationResult(validateCommitMessage('build: blablabla'), VALID);
     });
 
     // We do not want to allow WIP. It is OK to fail the PR build in this case to show that there is
@@ -127,30 +125,25 @@ describe('validate-commit-message.js', () => {
     it('should not allow "WIP: ..." syntax', () => {
       const msg = 'WIP: fix: something';
 
-      expect(validateCommitMessage(msg)).toBe(INVALID);
-      expect(lastError).toContain(`'WIP' is not an allowed type.\n => TYPES: ${TYPES}`);
+      expectValidationResult(
+          validateCommitMessage(msg), INVALID,
+          [`'WIP' is not an allowed type.\n => TYPES: ${TYPES}`]);
     });
 
     describe('(revert)', () => {
       it('should allow valid "revert: ..." syntaxes', () => {
-        expect(validateCommitMessage('revert: anything')).toBe(VALID);
-        expect(lastError).toBe('');
-
-        expect(validateCommitMessage('Revert: "anything"')).toBe(VALID);
-        expect(lastError).toBe('');
-
-        expect(validateCommitMessage('revert anything')).toBe(VALID);
-        expect(lastError).toBe('');
-
-        expect(validateCommitMessage('rEvErT anything')).toBe(VALID);
-        expect(lastError).toBe('');
+        expectValidationResult(validateCommitMessage('revert: anything'), VALID);
+        expectValidationResult(validateCommitMessage('Revert: "anything"'), VALID);
+        expectValidationResult(validateCommitMessage('revert anything'), VALID);
+        expectValidationResult(validateCommitMessage('rEvErT anything'), VALID);
       });
 
       it('should not allow "revert(scope): ..." syntax', () => {
         const msg = 'revert(compiler): reduce generated code payload size by 65%';
 
-        expect(validateCommitMessage(msg)).toBe(INVALID);
-        expect(lastError).toContain(`'revert' is not an allowed type.\n => TYPES: ${TYPES}`);
+        expectValidationResult(
+            validateCommitMessage(msg), INVALID,
+            [`'revert' is not an allowed type.\n => TYPES: ${TYPES}`]);
       });
 
       // https://github.com/angular/angular/issues/23479
@@ -158,28 +151,26 @@ describe('validate-commit-message.js', () => {
         const msg =
             'Revert "fix(compiler): Pretty print object instead of [Object object] (#22689)" (#23442)';
 
-        expect(validateCommitMessage(msg)).toBe(VALID);
-        expect(lastError).toBe('');
+        expectValidationResult(validateCommitMessage(msg), VALID);
       });
     });
 
     describe('(squash)', () => {
       describe('without `disallowSquash`', () => {
         it('should return commits as valid', () => {
-          expect(validateCommitMessage('squash! feat(core): add feature')).toBe(VALID);
-          expect(validateCommitMessage('squash! fix: a bug')).toBe(VALID);
-          expect(validateCommitMessage('squash! fix a typo')).toBe(VALID);
+          expectValidationResult(validateCommitMessage('squash! feat(core): add feature'), VALID);
+          expectValidationResult(validateCommitMessage('squash! fix: a bug'), VALID);
+          expectValidationResult(validateCommitMessage('squash! fix a typo'), VALID);
         });
       });
 
       describe('with `disallowSquash`', () => {
         it('should fail', () => {
-          expect(validateCommitMessage('fix(core): something', {disallowSquash: true})).toBe(VALID);
-          expect(validateCommitMessage('squash! fix(core): something', {
-            disallowSquash: true
-          })).toBe(INVALID);
-          expect(lastError).toContain(
-              'The commit must be manually squashed into the target commit');
+          expectValidationResult(
+              validateCommitMessage('fix(core): something', {disallowSquash: true}), VALID);
+          expectValidationResult(
+              validateCommitMessage('squash! fix(core): something', {disallowSquash: true}),
+              INVALID, ['The commit must be manually squashed into the target commit']);
         });
       });
     });
@@ -187,9 +178,9 @@ describe('validate-commit-message.js', () => {
     describe('(fixup)', () => {
       describe('without `nonFixupCommitHeaders`', () => {
         it('should return commits as valid', () => {
-          expect(validateCommitMessage('fixup! feat(core): add feature')).toBe(VALID);
-          expect(validateCommitMessage('fixup! fix: a bug')).toBe(VALID);
-          expect(validateCommitMessage('fixup! fixup! fix: a bug')).toBe(VALID);
+          expectValidationResult(validateCommitMessage('fixup! feat(core): add feature'), VALID);
+          expectValidationResult(validateCommitMessage('fixup! fix: a bug'), VALID);
+          expectValidationResult(validateCommitMessage('fixup! fixup! fix: a bug'), VALID);
         });
       });
 
@@ -197,36 +188,39 @@ describe('validate-commit-message.js', () => {
         it('should check that the fixup commit matches a non-fixup one', () => {
           const msg = 'fixup! foo';
 
-          expect(validateCommitMessage(
-                     msg, {disallowSquash: false, nonFixupCommitHeaders: ['foo', 'bar', 'baz']}))
-              .toBe(VALID);
-          expect(validateCommitMessage(
-                     msg, {disallowSquash: false, nonFixupCommitHeaders: ['bar', 'baz', 'foo']}))
-              .toBe(VALID);
-          expect(validateCommitMessage(
-                     msg, {disallowSquash: false, nonFixupCommitHeaders: ['baz', 'foo', 'bar']}))
-              .toBe(VALID);
+          expectValidationResult(
+              validateCommitMessage(
+                  msg, {disallowSquash: false, nonFixupCommitHeaders: ['foo', 'bar', 'baz']}),
+              VALID);
+          expectValidationResult(
+              validateCommitMessage(
+                  msg, {disallowSquash: false, nonFixupCommitHeaders: ['bar', 'baz', 'foo']}),
+              VALID);
+          expectValidationResult(
+              validateCommitMessage(
+                  msg, {disallowSquash: false, nonFixupCommitHeaders: ['baz', 'foo', 'bar']}),
+              VALID);
 
-          expect(validateCommitMessage(
-                     msg, {disallowSquash: false, nonFixupCommitHeaders: ['qux', 'quux', 'quuux']}))
-              .toBe(INVALID);
-          expect(lastError).toContain(
-              'Unable to find match for fixup commit among prior commits: \n' +
-              '      qux\n' +
-              '      quux\n' +
-              '      quuux');
+          expectValidationResult(
+              validateCommitMessage(
+                  msg, {disallowSquash: false, nonFixupCommitHeaders: ['qux', 'quux', 'quuux']}),
+              INVALID,
+              ['Unable to find match for fixup commit among prior commits: \n' +
+               '      qux\n' +
+               '      quux\n' +
+               '      quuux']);
         });
 
         it('should fail if `nonFixupCommitHeaders` is empty', () => {
-          expect(validateCommitMessage('refactor(core): make reactive', {
-            disallowSquash: false,
-            nonFixupCommitHeaders: []
-          })).toBe(VALID);
-          expect(validateCommitMessage(
-                     'fixup! foo', {disallowSquash: false, nonFixupCommitHeaders: []}))
-              .toBe(INVALID);
-          expect(lastError).toContain(
-              `Unable to find match for fixup commit among prior commits: -`);
+          expectValidationResult(
+              validateCommitMessage(
+                  'refactor(core): make reactive',
+                  {disallowSquash: false, nonFixupCommitHeaders: []}),
+              VALID);
+          expectValidationResult(
+              validateCommitMessage(
+                  'fixup! foo', {disallowSquash: false, nonFixupCommitHeaders: []}),
+              INVALID, [`Unable to find match for fixup commit among prior commits: -`]);
         });
       });
     });
@@ -246,24 +240,27 @@ describe('validate-commit-message.js', () => {
       });
 
       it('should fail validation if the body is shorter than `minBodyLength`', () => {
-        expect(validateCommitMessage(
-                   'fix(core): something\n\n Explanation of the motivation behind this change'))
-            .toBe(VALID);
-        expect(validateCommitMessage('fix(core): something\n\n too short')).toBe(INVALID);
-        expect(lastError).toContain(
-            'The commit message body does not meet the minimum length of 30 characters');
-        expect(validateCommitMessage('fix(core): something')).toBe(INVALID);
-        expect(lastError).toContain(
-            'The commit message body does not meet the minimum length of 30 characters');
+        expectValidationResult(
+            validateCommitMessage(
+                'fix(core): something\n\n Explanation of the motivation behind this change'),
+            VALID);
+        expectValidationResult(
+            validateCommitMessage('fix(core): something\n\n too short'), INVALID,
+            ['The commit message body does not meet the minimum length of 30 characters']);
+        expectValidationResult(validateCommitMessage('fix(core): something'), INVALID, [
+
+          'The commit message body does not meet the minimum length of 30 characters'
+        ]);
       });
 
       it('should pass validation if the body is shorter than `minBodyLength` but the commit type is in the `minBodyLengthTypeExclusions` list',
          () => {
-           expect(validateCommitMessage('docs: just fixing a typo')).toBe(VALID);
-           expect(validateCommitMessage('docs(core): just fixing a typo')).toBe(VALID);
-           expect(validateCommitMessage(
-                      'docs(core): just fixing a typo\n\nThis was just a silly typo.'))
-               .toBe(VALID);
+           expectValidationResult(validateCommitMessage('docs: just fixing a typo'), VALID);
+           expectValidationResult(validateCommitMessage('docs(core): just fixing a typo'), VALID);
+           expectValidationResult(
+               validateCommitMessage(
+                   'docs(core): just fixing a typo\n\nThis was just a silly typo.'),
+               VALID);
          });
     });
   });

dev-infra/commit-message/validate.ts

@@ -8,7 +8,7 @@
 import {error} from '../utils/console';
 
 import {COMMIT_TYPES, getCommitMessageConfig, ScopeRequirement} from './config';
-import {parseCommitMessage} from './parse';
+import {parseCommitMessage, ParsedCommitMessage} from './parse';
 
 /** Options for commit message validation. */
 export interface ValidateCommitMessageOptions {
@@ -16,133 +16,147 @@ export interface ValidateCommitMessageOptions {
   nonFixupCommitHeaders?: string[];
 }
 
+/** The result of a commit message validation check. */
+export interface ValidateCommitMessageResult {
+  valid: boolean;
+  errors: string[];
+  commit: ParsedCommitMessage;
+}
+
 /** Regex matching a URL for an entire commit body line. */
 const COMMIT_BODY_URL_LINE_RE = /^https?:\/\/.*$/;
 
 /** Validate a commit message against using the local repo's config. */
 export function validateCommitMessage(
-    commitMsg: string, options: ValidateCommitMessageOptions = {}) {
-  function printError(errorMessage: string) {
-    error(
-        `INVALID COMMIT MSG: \n` +
-        `${'─'.repeat(40)}\n` +
-        `${commitMsg}\n` +
-        `${'─'.repeat(40)}\n` +
-        `ERROR: \n` +
-        `  ${errorMessage}` +
-        `\n\n` +
-        `The expected format for a commit is: \n` +
-        `<type>(<scope>): <subject>\n\n<body>`);
-  }
-
+    commitMsg: string, options: ValidateCommitMessageOptions = {}): ValidateCommitMessageResult {
   const config = getCommitMessageConfig().commitMessage;
   const commit = parseCommitMessage(commitMsg);
+  const errors: string[] = [];
 
-  ////////////////////////////////////
-  // Checking revert, squash, fixup //
-  ////////////////////////////////////
+  /** Perform the validation checks against the parsed commit. */
+  function validateCommitAndCollectErrors() {
+    // TODO(josephperrott): Remove early return calls when commit message errors are found
 
-  // All revert commits are considered valid.
-  if (commit.isRevert) {
-    return true;
-  }
+    ////////////////////////////////////
+    // Checking revert, squash, fixup //
+    ////////////////////////////////////
 
-  // All squashes are considered valid, as the commit will be squashed into another in
-  // the git history anyway, unless the options provided to not allow squash commits.
-  if (commit.isSquash) {
-    if (options.disallowSquash) {
-      printError('The commit must be manually squashed into the target commit');
+    // All revert commits are considered valid.
+    if (commit.isRevert) {
+      return true;
+    }
+
+    // All squashes are considered valid, as the commit will be squashed into another in
+    // the git history anyway, unless the options provided to not allow squash commits.
+    if (commit.isSquash) {
+      if (options.disallowSquash) {
+        errors.push('The commit must be manually squashed into the target commit');
+        return false;
+      }
+      return true;
+    }
+
+    // Fixups commits are considered valid, unless nonFixupCommitHeaders are provided to check
+    // against. If `nonFixupCommitHeaders` is not empty, we check whether there is a corresponding
+    // non-fixup commit (i.e. a commit whose header is identical to this commit's header after
+    // stripping the `fixup! ` prefix), otherwise we assume this verification will happen in another
+    // check.
+    if (commit.isFixup) {
+      if (options.nonFixupCommitHeaders && !options.nonFixupCommitHeaders.includes(commit.header)) {
+        errors.push(
+            'Unable to find match for fixup commit among prior commits: ' +
+            (options.nonFixupCommitHeaders.map(x => `\n      ${x}`).join('') || '-'));
+        return false;
+      }
+
+      return true;
+    }
+
+    ////////////////////////////
+    // Checking commit header //
+    ////////////////////////////
+    if (commit.header.length > config.maxLineLength) {
+      errors.push(`The commit message header is longer than ${config.maxLineLength} characters`);
       return false;
     }
-    return true;
-  }
 
-  // Fixups commits are considered valid, unless nonFixupCommitHeaders are provided to check
-  // against. If `nonFixupCommitHeaders` is not empty, we check whether there is a corresponding
-  // non-fixup commit (i.e. a commit whose header is identical to this commit's header after
-  // stripping the `fixup! ` prefix), otherwise we assume this verification will happen in another
-  // check.
-  if (commit.isFixup) {
-    if (options.nonFixupCommitHeaders && !options.nonFixupCommitHeaders.includes(commit.header)) {
-      printError(
-          'Unable to find match for fixup commit among prior commits: ' +
-          (options.nonFixupCommitHeaders.map(x => `\n      ${x}`).join('') || '-'));
+    if (!commit.type) {
+      errors.push(`The commit message header does not match the expected format.`);
+      return false;
+    }
+
+    if (COMMIT_TYPES[commit.type] === undefined) {
+      errors.push(`'${commit.type}' is not an allowed type.\n => TYPES: ${
+          Object.keys(COMMIT_TYPES).join(', ')}`);
+      return false;
+    }
+
+    /** The scope requirement level for the provided type of the commit message. */
+    const scopeRequirementForType = COMMIT_TYPES[commit.type].scope;
+
+    if (scopeRequirementForType === ScopeRequirement.Forbidden && commit.scope) {
+      errors.push(`Scopes are forbidden for commits with type '${commit.type}', but a scope of '${
+          commit.scope}' was provided.`);
+      return false;
+    }
+
+    if (scopeRequirementForType === ScopeRequirement.Required && !commit.scope) {
+      errors.push(
+          `Scopes are required for commits with type '${commit.type}', but no scope was provided.`);
+      return false;
+    }
+
+    if (commit.scope && !config.scopes.includes(commit.scope)) {
+      errors.push(
+          `'${commit.scope}' is not an allowed scope.\n => SCOPES: ${config.scopes.join(', ')}`);
+      return false;
+    }
+
+    // Commits with the type of `release` do not require a commit body.
+    if (commit.type === 'release') {
+      return true;
+    }
+
+    //////////////////////////
+    // Checking commit body //
+    //////////////////////////
+
+    if (!config.minBodyLengthTypeExcludes?.includes(commit.type) &&
+        commit.bodyWithoutLinking.trim().length < config.minBodyLength) {
+      errors.push(`The commit message body does not meet the minimum length of ${
+          config.minBodyLength} characters`);
+      return false;
+    }
+
+    const bodyByLine = commit.body.split('\n');
+    const lineExceedsMaxLength = bodyByLine.some(line => {
+      // Check if any line exceeds the max line length limit. The limit is ignored for
+      // lines that just contain an URL (as these usually cannot be wrapped or shortened).
+      return line.length > config.maxLineLength && !COMMIT_BODY_URL_LINE_RE.test(line);
+    });
+
+    if (lineExceedsMaxLength) {
+      errors.push(
+          `The commit message body contains lines greater than ${config.maxLineLength} characters`);
       return false;
     }
 
     return true;
   }
 
-  ////////////////////////////
-  // Checking commit header //
-  ////////////////////////////
-  if (commit.header.length > config.maxLineLength) {
-    printError(`The commit message header is longer than ${config.maxLineLength} characters`);
-    return false;
-  }
-
-  if (!commit.type) {
-    printError(`The commit message header does not match the expected format.`);
-    return false;
-  }
-
-
-
-  if (COMMIT_TYPES[commit.type] === undefined) {
-    printError(`'${commit.type}' is not an allowed type.\n => TYPES: ${
-        Object.keys(COMMIT_TYPES).join(', ')}`);
-    return false;
-  }
-
-  /** The scope requirement level for the provided type of the commit message. */
-  const scopeRequirementForType = COMMIT_TYPES[commit.type].scope;
-
-  if (scopeRequirementForType === ScopeRequirement.Forbidden && commit.scope) {
-    printError(`Scopes are forbidden for commits with type '${commit.type}', but a scope of '${
-        commit.scope}' was provided.`);
-    return false;
-  }
-
-  if (scopeRequirementForType === ScopeRequirement.Required && !commit.scope) {
-    printError(
-        `Scopes are required for commits with type '${commit.type}', but no scope was provided.`);
-    return false;
-  }
-
-  if (commit.scope && !config.scopes.includes(commit.scope)) {
-    printError(
-        `'${commit.scope}' is not an allowed scope.\n => SCOPES: ${config.scopes.join(', ')}`);
-    return false;
-  }
-
-  // Commits with the type of `release` do not require a commit body.
-  if (commit.type === 'release') {
-    return true;
-  }
-
-  //////////////////////////
-  // Checking commit body //
-  //////////////////////////
-
-  if (!config.minBodyLengthTypeExcludes?.includes(commit.type) &&
-      commit.bodyWithoutLinking.trim().length < config.minBodyLength) {
-    printError(`The commit message body does not meet the minimum length of ${
-        config.minBodyLength} characters`);
-    return false;
-  }
-
-  const bodyByLine = commit.body.split('\n');
-  const lineExceedsMaxLength = bodyByLine.some(line => {
-    // Check if any line exceeds the max line length limit. The limit is ignored for
-    // lines that just contain an URL (as these usually cannot be wrapped or shortened).
-    return line.length > config.maxLineLength && !COMMIT_BODY_URL_LINE_RE.test(line);
-  });
-
-  if (lineExceedsMaxLength) {
-    printError(
-        `The commit message body contains lines greater than ${config.maxLineLength} characters`);
-    return false;
-  }
-
-  return true;
+  return {valid: validateCommitAndCollectErrors(), errors, commit};
+}
+
+
+/** Print the error messages from the commit message validation to the console. */
+export function printValidationErrors(errors: string[], print = error) {
+  print.group(`Error${errors.length === 1 ? '' : 's'}:`);
+  errors.forEach(line => print(line));
+  print.groupEnd();
+  print();
+  print('The expected format for a commit is: ');
+  print('<type>(<scope>): <summary>');
+  print();
+  print('<body>');
+  print();
 }

dev-infra/commit-message/wizard/cli.ts

@@ -0,0 +1,54 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+import {Arguments, Argv, CommandModule} from 'yargs';
+
+import {CommitMsgSource} from '../commit-message-source';
+
+import {runWizard} from './wizard';
+
+
+export interface WizardOptions {
+  filePath: string;
+  commitSha: string|undefined;
+  source: CommitMsgSource|undefined;
+}
+
+/** Builds the command. */
+function builder(yargs: Argv) {
+  return yargs
+      .positional('filePath', {
+        description: 'The file path to write the generated commit message into',
+        type: 'string',
+        demandOption: true,
+      })
+      .positional('source', {
+        choices: ['message', 'template', 'merge', 'squash', 'commit'] as const,
+        description: 'The source of the commit message as described here: ' +
+            'https://git-scm.com/docs/githooks#_prepare_commit_msg'
+      })
+      .positional('commitSha', {
+        description: 'The commit sha if source is set to `commit`',
+        type: 'string',
+      });
+}
+
+/** Handles the command. */
+async function handler(args: Arguments<WizardOptions>) {
+  await runWizard(args);
+}
+
+/** yargs command module describing the command.  */
+export const WizardModule: CommandModule<{}, WizardOptions> = {
+  handler,
+  builder,
+  command: 'wizard <filePath> [source] [commitSha]',
+  // Description: Run the wizard to build a base commit message before opening to complete.
+  // No describe is defiend to hide the command from the --help.
+  describe: false,
+};

dev-infra/commit-message/wizard/wizard.ts

@@ -7,15 +7,12 @@
  */
 import {writeFileSync} from 'fs';
 
-import {info} from '../utils/console';
+import {getUserConfig} from '../../utils/config';
+import {debug, info} from '../../utils/console';
 
-import {buildCommitMessage} from './builder';
+import {buildCommitMessage} from '../builder';
+import {CommitMsgSource} from '../commit-message-source';
 
-/**
- * The source triggering the git commit message creation.
- * As described in: https://git-scm.com/docs/githooks#_prepare_commit_msg
- */
-export type PrepareCommitMsgHookSource = 'message'|'template'|'merge'|'squash'|'commit';
 
 /** The default commit message used if the wizard does not procude a commit message. */
 const defaultCommitMessage = `<type>(<scope>): <summary>
@@ -24,11 +21,16 @@ const defaultCommitMessage = `<type>(<scope>): <summary>
 #  lines at 100 characters.>\n\n`;
 
 export async function runWizard(
-    args: {filePath: string, source?: PrepareCommitMsgHookSource, commitSha?: string}) {
-  // TODO(josephperrott): Add support for skipping wizard with local untracked config file
+    args: {filePath: string, source?: CommitMsgSource, commitSha?: string}) {
+  if (getUserConfig().commitMessage?.disableWizard) {
+    debug('Skipping commit message wizard due to enabled `commitMessage.disableWizard` option in');
+    debug('user config.');
+    process.exitCode = 0;
+    return;
+  }
 
   if (args.source !== undefined) {
-    info(`Skipping commit message wizard due because the commit was created via '${
+    info(`Skipping commit message wizard because the commit was created via '${
         args.source}' source`);
     process.exitCode = 0;
     return;

dev-infra/pr/common/BUILD.bazel

@@ -3,6 +3,7 @@ load("@npm_bazel_typescript//:index.bzl", "ts_library")
 ts_library(
     name = "common",
     srcs = glob(["*.ts"]),
+    module_name = "@angular/dev-infra-private/pr/common",
     visibility = ["//dev-infra:__subpackages__"],
     deps = [
         "//dev-infra/utils",

dev-infra/pr/merge/index.ts

@@ -33,6 +33,10 @@ import {MergeResult, MergeStatus, PullRequestMergeTask} from './task';
 export async function mergePullRequest(
     prNumber: number, githubToken: string, projectRoot: string = getRepoBaseDir(),
     config?: MergeConfigWithRemote) {
+  // Set the environment variable to skip all git commit hooks triggered by husky. We are unable to
+  // rely on `---no-verify` as some hooks still run, notably the `prepare-commit-msg` hook.
+  process.env['HUSKY_SKIP_HOOKS'] = '1';
+
   const api = await createPullRequestMergeTask(githubToken, projectRoot, config);
 
   // Perform the merge. Force mode can be activated through a command line flag.

dev-infra/tmpl-package.json

@@ -12,11 +12,13 @@
     "@angular/benchpress": "0.2.1",
     "@octokit/graphql": "<from-root>",
     "@octokit/types": "<from-root>",
+    "@octokit/rest": "<from-root>",
     "brotli": "<from-root>",
     "chalk": "<from-root>",
     "cli-progress": "<from-root>",
     "glob": "<from-root>",
     "inquirer": "<from-root>",
+    "inquirer-autocomplete-prompt": "<from-root>",
     "minimatch": "<from-root>",
     "multimatch": "<from-root>",
     "node-fetch": "<from-root>",
@@ -26,9 +28,7 @@
     "tslib": "<from-root>",
     "typed-graphqlify": "<from-root>",
     "yaml": "<from-root>",
-    "yargs": "<from-root>"
-  },
-  "peerDependencies": {
+    "yargs": "<from-root>",
     "@bazel/buildifier": "<from-root>",
     "clang-format": "<from-root>",
     "protractor": "<from-root>",

dev-infra/ts-circular-dependencies/index.ts

@@ -112,7 +112,8 @@ export function main(
   if (fixedCircularDeps.length !== 0) {
     error(yellow(`   Fixed circular dependencies that need to be removed from the golden:`));
     fixedCircularDeps.forEach(c => error(`     • ${convertReferenceChainToString(c)}`));
-    error();
+    info(yellow(`\n   Total: ${newCircularDeps.length} new cycle(s), ${
+        fixedCircularDeps.length} fixed cycle(s). \n`));
     if (approveCommand) {
       info(yellow(`   Please approve the new golden with: ${approveCommand}`));
     } else {

dev-infra/utils/BUILD.bazel

@@ -12,13 +12,11 @@ ts_library(
         "@npm//@octokit/graphql",
         "@npm//@octokit/rest",
         "@npm//@octokit/types",
-        "@npm//@types/fs-extra",
         "@npm//@types/inquirer",
         "@npm//@types/node",
         "@npm//@types/shelljs",
         "@npm//@types/yargs",
         "@npm//chalk",
-        "@npm//fs-extra",
         "@npm//inquirer",
         "@npm//inquirer-autocomplete-prompt",
         "@npm//shelljs",

dev-infra/utils/config.ts

@@ -9,7 +9,7 @@
 import {existsSync} from 'fs';
 import {dirname, join} from 'path';
 
-import {error} from './console';
+import {debug, error} from './console';
 import {exec} from './shelljs';
 import {isTsNodeAvailable} from './ts-node';
 
@@ -49,7 +49,16 @@ export type NgDevConfig<T = {}> = CommonConfig&T;
 const CONFIG_FILE_PATH = '.ng-dev/config';
 
 /** The configuration for ng-dev. */
-let CONFIG: {}|null = null;
+let cachedConfig: NgDevConfig|null = null;
+
+/**
+ * The filename expected for local user config, without the file extension to allow a typescript,
+ * javascript or json file to be used.
+ */
+const USER_CONFIG_FILE_PATH = '.ng-dev.user';
+
+/** The local user configuration for ng-dev. */
+let userConfig: {[key: string]: any}|null = null;
 
 /**
  * Get the configuration from the file system, returning the already loaded
@@ -57,15 +66,15 @@ let CONFIG: {}|null = null;
  */
 export function getConfig(): NgDevConfig {
   // If the global config is not defined, load it from the file system.
-  if (CONFIG === null) {
+  if (cachedConfig === null) {
     // The full path to the configuration file.
     const configPath = join(getRepoBaseDir(), CONFIG_FILE_PATH);
-    // Set the global config object.
-    CONFIG = readConfigFile(configPath);
+    // Read the configuration and validate it before caching it for the future.
+    cachedConfig = validateCommonConfig(readConfigFile(configPath));
   }
-  // Return a clone of the global config to ensure that a new instance of the config is returned
-  // each time, preventing unexpected effects of modifications to the config object.
-  return validateCommonConfig({...CONFIG});
+  // Return a clone of the cached global config to ensure that a new instance of the config
+  // is returned each time, preventing unexpected effects of modifications to the config object.
+  return {...cachedConfig};
 }
 
 /** Validate the common configuration has been met for the ng-dev command. */
@@ -86,8 +95,11 @@ function validateCommonConfig(config: Partial<NgDevConfig>) {
   return config as NgDevConfig;
 }
 
-/** Resolves and reads the specified configuration file. */
-function readConfigFile(configPath: string): object {
+/**
+ * Resolves and reads the specified configuration file, optionally returning an empty object if the
+ * configuration file cannot be read.
+ */
+function readConfigFile(configPath: string, returnEmptyObjectOnError = false): object {
   // If the the `.ts` extension has not been set up already, and a TypeScript based
   // version of the given configuration seems to exist, set up `ts-node` if available.
   if (require.extensions['.ts'] === undefined && existsSync(`${configPath}.ts`) &&
@@ -103,7 +115,12 @@ function readConfigFile(configPath: string): object {
   try {
     return require(configPath);
   } catch (e) {
-    error('Could not read configuration file.');
+    if (returnEmptyObjectOnError) {
+      debug(`Could not read configuration file at ${configPath}, returning empty object instead.`);
+      debug(e);
+      return {};
+    }
+    error(`Could not read configuration file at ${configPath}.`);
     error(e);
     process.exit(1);
   }
@@ -135,3 +152,23 @@ export function getRepoBaseDir() {
   }
   return baseRepoDir.trim();
 }
+
+/**
+ * Get the local user configuration from the file system, returning the already loaded copy if it is
+ * defined.
+ *
+ * @returns The user configuration object, or an empty object if no user configuration file is
+ * present. The object is an untyped object as there are no required user configurations.
+ */
+export function getUserConfig() {
+  // If the global config is not defined, load it from the file system.
+  if (userConfig === null) {
+    // The full path to the configuration file.
+    const configPath = join(getRepoBaseDir(), USER_CONFIG_FILE_PATH);
+    // Set the global config object.
+    userConfig = readConfigFile(configPath, true);
+  }
+  // Return a clone of the user config to ensure that a new instance of the config is returned
+  // each time, preventing unexpected effects of modifications to the config object.
+  return {...userConfig};
+}

dev-infra/utils/console.ts

@@ -7,7 +7,7 @@
  */
 
 import chalk from 'chalk';
-import {writeFileSync} from 'fs-extra';
+import {writeFileSync} from 'fs';
 import {createPromptModule, ListChoiceOptions, prompt} from 'inquirer';
 import * as inquirerAutocomplete from 'inquirer-autocomplete-prompt';
 import {join} from 'path';
@@ -196,6 +196,9 @@ export function captureLogOutputForCommand(argv: Arguments) {
     /** Path to the log file location. */
     const logFilePath = join(getRepoBaseDir(), '.ng-dev.log');
 
+    // Strip ANSI escape codes from log outputs.
+    LOGGED_TEXT = LOGGED_TEXT.replace(/\x1B\[([0-9]{1,3}(;[0-9]{1,2})?)?[mGK]/g, '');
+
     writeFileSync(logFilePath, LOGGED_TEXT);
 
     // For failure codes greater than 1, the new logged lines should be written to a specific log