diff --git a/.pullapprove.yml b/.pullapprove.yml
index 96dbe6382cb..3eba6031191 100644
--- a/.pullapprove.yml
+++ b/.pullapprove.yml
@@ -925,8 +925,7 @@ groups:
conditions:
- >
contains_any_globs(files, [
- 'docs/PUBLIC_API.md',
- 'docs/RELEASE_SCHEDULE.md',
+ 'contributing-docs/public-api-surface.md',
'aio/content/guide/npm-packages.md',
'aio/content/guide/browser-support.md',
'aio/content/guide/releases.md',
@@ -1184,8 +1183,8 @@ groups:
'.ng-dev/**/{*,.*}',
'.vscode/**/{*,.*}',
'.yarn/**/{*,.*}',
- 'docs/*.md',
- 'docs/images/**/{*,.*}',
+ 'contributing-docs/*.md',
+ 'contributing-docs/images/**/{*,.*}',
'goldens/{*,.*}',
'goldens/public-api/manage.js',
'modules/{*,.*}',
@@ -1230,7 +1229,6 @@ groups:
- >
contains_any_globs(files.exclude("goldens/public-api/manage.js"), [
'goldens/public-api/**/{*,.*}',
- 'docs/NAMING.md',
'aio/content/guide/angular-package-format.md',
'aio/content/guide/glossary.md',
'aio/content/guide/styleguide.md',
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index ac6368d9ae4..44329c3b80b 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -32,7 +32,7 @@ Stack Overflow is a much better place to ask questions since:
To save your and our time, we will systematically close all issues that are requests for general support and redirect people to Stack Overflow.
-If you would like to chat about the question in real-time, you can reach out via [our Discord server][discord].
+If you would like to chat about the question in real-time, you can reach out via [the Angular community Discord server][discord].
## Found a Bug?
@@ -138,7 +138,7 @@ If we ask for changes via code reviews then:
git push
```
- For more info on working with fixup commits see [here](docs/FIXUP_COMMITS.md).
+ For more info on working with fixup commits see [here](./contributing-docs/using-fixup-commits.md).
That's it! Thank you for your contribution!
@@ -207,7 +207,7 @@ To ensure consistency throughout the source code, keep these rules in mind as yo
* All public API methods **must be documented**.
* We follow [Google's JavaScript Style Guide][js-style-guide], but wrap all code at **100 characters**.
- An automated formatter is available, see [DEVELOPER.md](docs/DEVELOPER.md#formatting-your-source-code).
+ An automated formatter is available, see [DEVELOPER.md](contributing-docs/building-and-testing-angular#formatting-your-source-code).
## Commit Message Format
@@ -392,7 +392,7 @@ The following documents can help you sort out issues with GitHub accounts and mu
[coc]: https://github.com/angular/code-of-conduct/blob/main/CODE_OF_CONDUCT.md
[commit-message-format]: https://docs.google.com/document/d/1QrDFcIiPjSLDn3EL15IJygNPiHORgU1_OOAqWjiDU5Y/edit#
[corporate-cla]: https://cla.developers.google.com/about/google-corporate
-[dev-doc]: https://github.com/angular/angular/blob/main/docs/DEVELOPER.md
+[dev-doc]: ./contributing-docs/building-and-testing-angular.md
[github]: https://github.com/angular/angular
[discord]: https://discord.gg/angular
[individual-cla]: https://cla.developers.google.com/about/google-individual
diff --git a/contributing-docs/auto-issue-locking.md b/contributing-docs/auto-issue-locking.md
new file mode 100644
index 00000000000..90190b475d7
--- /dev/null
+++ b/contributing-docs/auto-issue-locking.md
@@ -0,0 +1,19 @@
+
+
+# Automatic conversation locking
+
+Closed issues and pull requests are locked automatically after 30 days of inactivity.
+
+## I want to comment on a locked conversation, what should I do?
+
+When an issue has been closed and inactive for over 30 days, the original context is likely
+outdated.
+If you encounter a similar or related issue in the current version, please open a new issue and
+provide up-to-date reproduction instructions.
+
+## Why lock conversations?
+
+Automatically locking closed, inactive issues guides people towards filing new issues with updated
+context rather than commenting on a "resolved" issue that contains out-of-date or unrelated
+information. As an example, someone may comment "I'm still having this issue", but without
+providing any of the additional information the team needs to investigate.
diff --git a/docs/BRANCHES.md b/contributing-docs/branches-and-versioning.md
similarity index 100%
rename from docs/BRANCHES.md
rename to contributing-docs/branches-and-versioning.md
diff --git a/docs/DEVELOPER.md b/contributing-docs/building-and-testing-angular.md
similarity index 59%
rename from docs/DEVELOPER.md
rename to contributing-docs/building-and-testing-angular.md
index f27179c8cde..403e287a2d7 100644
--- a/docs/DEVELOPER.md
+++ b/contributing-docs/building-and-testing-angular.md
@@ -19,22 +19,27 @@ if you'd like to contribute to Angular.
## Prerequisite Software
Before you can build and test Angular, you must install and configure the
-following products on your development machine:
+following on your development machine:
-* [Git](https://git-scm.com/) and/or the [**GitHub app**](https://desktop.github.com/) (for Mac and Windows);
- [GitHub's Guide to Installing Git](https://help.github.com/articles/set-up-git) is a good source of information.\
+* [Git](https://git-scm.com/) and/or the [**GitHub app**](https://desktop.github.com/) (for Mac and
+ Windows);
+ [GitHub's Guide to Installing Git](https://help.github.com/articles/set-up-git) is a good source
+ of information.\
**Windows Users**: Git Bash or an equivalent shell is required\
- *Windows Powershell and cmd shells are not supported [#46780](https://github.com/angular/angular/issues/46780) so some commands might fail*
+ *Windows Powershell and cmd shells are not
+ supported [#46780](https://github.com/angular/angular/issues/46780) so some commands might fail*
-* [Node.js](https://nodejs.org), (version specified in [`.nvmrc`](../.nvmrc)) which is used to run a development web server,
+* [Node.js](https://nodejs.org), (version specified in [`.nvmrc`](../.nvmrc)) which is used to run a
+ development web server,
run tests, and generate distributable files.
- `.nvmrc` is read by [nvm](https://github.com/nvm-sh/nvm) commands like `nvm install` and `nvm use`.
+ `.nvmrc` is read by [nvm](https://github.com/nvm-sh/nvm) commands like `nvm install`
+ and `nvm use`.
-* [Yarn](https://yarnpkg.com) (version specified in the engines field of [`package.json`](../package.json)) which is used to install dependencies.
+* [Yarn](https://yarnpkg.com) (version specified in the engines field
+ of [`package.json`](../package.json)) which is used to install dependencies.
-* On Windows: [MSYS2](https://www.msys2.org/) which is used by Bazel. Follow the [instructions](https://bazel.build/install/windows#installing-compilers-and-language-runtimes)
-
-* Optional: [Java](https://openjdk.java.net/) version 7 or higher than required by [Closure Compiler](https://developers.google.com/closure/compiler). Most developers will not need this. Java is required for running some integration tests.
+* On Windows: [MSYS2](https://www.msys2.org/) which is used by Bazel. Follow
+ the [instructions](https://bazel.build/install/windows#installing-compilers-and-language-runtimes)
## Getting the Sources
@@ -81,15 +86,18 @@ yarn build
Bazel is used as the primary tool for building and testing Angular.
-To see how to run and debug Angular tests locally please refer to the Bazel [Testing Angular](./BAZEL.md#testing-angular) section.
+To see how to run and debug Angular tests locally please refer to the
+Bazel [Testing Angular](./BAZEL.md#testing-angular) section.
-Note that you should execute all test suites before submitting a PR to GitHub (`yarn test //packages/...`).
+Note that you should execute all test suites before submitting a PR to
+GitHub (`yarn test //packages/...`).
-However, affected tests will be executed on our CI infrastructure. So if you forgot to run some affected tests which would fail, GitHub will indicate the error state and present you the failures.
+However, affected tests will be executed on our CI infrastructure. So if you forgot to run some
+affected tests which would fail, GitHub will indicate the error state and present you the failures.
PRs can only be merged if the code is formatted properly and all tests are passing.
-
+
@@ -100,6 +108,7 @@ use changes in another library or project. To do this developers can build Angul
using `yarn link` build a local project with the created artifacts.
This can be done by running:
+
```sh
yarn ng-dev misc build-and-link
```
@@ -108,11 +117,17 @@ yarn ng-dev misc build-and-link
#### Cache
-When making changes to Angular packages and testing in a local library/project you need to run `ng cache disable` to disable the Angular CLI disk cache. If you are making changes that are not reflected in your locally served library/project, verify if you have [CLI Cache](https://angular.io/guide/workspace-config#cache-options) disabled.
+When making changes to Angular packages and testing in a local library/project you need to
+run `ng cache disable` to disable the Angular CLI disk cache. If you are making changes that are not
+reflected in your locally served library/project, verify if you
+have [CLI Cache](https://angular.io/guide/workspace-config#cache-options) disabled.
#### Invoking the Angular CLI
-The Angular CLI needs to be invoked using Node.js [`--preserve-symlinks`](https://nodejs.org/api/cli.html#--preserve-symlinks) flag. Otherwise the symbolic links will be resolved using their real path which causes node module resolution to fail.
+The Angular CLI needs to be invoked using
+Node.js [`--preserve-symlinks`](https://nodejs.org/api/cli.html#--preserve-symlinks) flag. Otherwise
+the symbolic links will be resolved using their real path which causes node module resolution to
+fail.
```sh
node --preserve-symlinks --preserve-symlinks-main node_modules/@angular/cli/lib/init.js serve
@@ -124,7 +139,9 @@ Angular uses [prettier](https://clang.llvm.org/docs/ClangFormat.html) to format
If the source code is not properly formatted, the CI will fail and the PR cannot be merged.
You can automatically format your code by running:
-- `yarn ng-dev format changed [shaOrRef]`: format only files changed since the provided sha/ref. `shaOrRef` defaults to `main`.
+
+- `yarn ng-dev format changed [shaOrRef]`: format only files changed since the provided
+ sha/ref. `shaOrRef` defaults to `main`.
- `yarn ng-dev format all`: format _all_ source code
- `yarn ng-dev format files `: format only provided files
@@ -138,7 +155,7 @@ $ yarn lint
## Publishing Snapshot Builds
-When a build of any branch on the upstream fork angular/angular is green on CircleCI, it
+When a build of any branch on the upstream fork angular/angular is green on CI, it
automatically publishes build artifacts to repositories in the Angular org. For example,
the `@angular/core` package is published to https://github.com/angular/core-builds.
@@ -146,51 +163,9 @@ You may find that your un-merged change needs some validation from external part
Rather than requiring them to pull your Pull Request and build Angular locally, they can depend on
snapshots of the Angular packages created based on the code in the Pull Request.
-### Getting Packages from Build Artifacts
-Each CI run for a Pull Request stores the built Angular packages as
-[build artifacts](https://circleci.com/docs/2.0/artifacts). The artifacts are not guaranteed to be
-available as a long-term distribution mechanism, but they are guaranteed to be available around the
-time of the build.
-
-You can access the artifacts for a specific CI run by going to the workflow page, clicking on the
-`publish_packages_as_artifacts` job and then switching to the "ARTIFACTS" tab.
-
-#### Archives for each Package
-On the "Artifacts" tab, there is a list of links to compressed archives for Angular packages. The
-archive names are of the format `-pr-.tgz` (for example
-`core-pr12345-a1b2c3d.tgz`).
-
-One can use the URL to the `.tgz` file for each package to install them as dependencies in a
-project they need to test the Pull Request changes against. Both
-[npm](https://docs.npmjs.com/cli/install.html) and [yarn](https://yarnpkg.com/lang/en/docs/cli/add)
-support installing dependencies from URLs to `.tgz` files, for example by updating the dependencies
-in `package.json` to point to the artifact URLs and then running `npm/yarn install`:
-
-```json
-"dependencies": {
- "@angular/common": "https://<...>.circle-artifacts.com/0/angular/common-pr12345-a1b2c3d.tgz",
- "@angular/core": "https://<...>.circle-artifacts.com/0/angular/core-pr12345-a1b2c3d.tgz",
- "...": "..."
-}
-```
-
-#### Download all Packages
-In addition to the individual package archives, a `.tgz` file including all packages is also
-available (named `all-pr-.tgz`). This can be used if one prefers to download all
-packages locally and test them by either of the following ways:
-
-1. Update the dependencies in `package.json` to point to the local uncompressed package directories.
-
-2. Directly copy the local uncompressed package directories into the `node_modules/` directory of a
- project.
-
-Note that (while faster) the second approach has limitations. For example:
-a. Any transitive dependencies of the copied packages will not be automatically updated.
-b. The packages need to be copied over every time `npm/yarn install` is run.
-c. Some package managers (such as `pnpm` or `yarn pnp`) might not work correctly.
-
### Publishing to GitHub Repos
-You can also manually publish `*-builds` snapshots just like our CircleCI build does for upstream
+
+You can also manually publish `*-builds` snapshots just like our CI build does for upstream
builds. Before being able to publish the packages, you need to build them locally by running the
`yarn build` command.
@@ -216,21 +191,26 @@ and create it if it doesn't exist.
#### VS Code
-1. Install [Bazel](https://marketplace.visualstudio.com/items?itemName=BazelBuild.vscode-bazel) extension for VS Code.
+1. Install [Bazel](https://marketplace.visualstudio.com/items?itemName=BazelBuild.vscode-bazel)
+ extension for VS Code.
#### WebStorm / IntelliJ
+
1. Install the [Bazel](https://plugins.jetbrains.com/plugin/8609-bazel) plugin
-1. You can find the settings under `Preferences->Other Settings->Bazel Settings`
+2. You can find the settings under `Preferences->Other Settings->Bazel Settings`
It will automatically recognize `*.bazel` and `*.bzl` files.
-
### Remote Build Execution and Remote Caching
-Bazel builds in the Angular repository use a shared cache. When a build occurs a hash of the inputs is computed
-and checked against available outputs in the shared cache. If an output is found, it is used as the output for the
+
+Bazel builds in the Angular repository use a shared cache. When a build occurs, a hash of the inputs
+is computed
+and checked against available outputs in the shared cache. If an output is found, it is used as the
+output for the
build action rather than performing the build locally.
> Remote Build Execution requires authentication as a google.com account.
#### --config=remote flag
+
The `--config=remote` flag can be added to enable remote execution of builds.
diff --git a/docs/BAZEL.md b/contributing-docs/building-with-bazel.md
similarity index 65%
rename from docs/BAZEL.md
rename to contributing-docs/building-with-bazel.md
index 4b5b7f0e017..b86aabca0b7 100644
--- a/docs/BAZEL.md
+++ b/contributing-docs/building-with-bazel.md
@@ -1,22 +1,21 @@
# Building Angular with Bazel
-Note: this doc is for developing Angular, it is _not_ public
+Note: This doc is for developing Angular. It is _not_ public
documentation for building an Angular application with Bazel.
The Bazel build tool (https://bazel.build) provides fast, reliable
-incremental builds. We plan to migrate Angular's build scripts to
-Bazel.
+incremental builds. The majority of Angular's code is built with Bazel.
-## Installation
+## Installation and running
-In order to ensure that everyone builds Angular in a _consistent_ way, Bazel
-will be installed through NPM. It's not necessary to install Bazel
-manually.
+Angular installs Bazel from npm rather than having contributors install Bazel
+directly. This ensures that everyone uses the same version of Bazel.
-The binaries for Bazel will be provided by the [`@bazel/bazelisk`](https://github.com/bazelbuild/bazelisk)
-NPM package and its platform-specific dependencies.
+The binaries for Bazel are provided by
+the [`@bazel/bazelisk`](https://github.com/bazelbuild/bazelisk)
+npm package and its platform-specific dependencies.
-You can access Bazel with the `yarn bazel` command
+You can run Bazel with the `yarn bazel` command.
## Configuration
@@ -40,9 +39,8 @@ want Bazel to create several symlinks in your project directory
- Build a package: `yarn bazel build packages/core`
- Build all packages: `yarn bazel build packages/...`
-You can use [ibazel] to get a "watch mode" that continuously
-keeps the outputs up-to-date as you save sources. Note this is
-new as of May 2017 and not very stable yet.
+You can use [ibazel] to run in a "watch mode" that continuously
+keeps the outputs up-to-date as you save sources.
[ibazel]: https://github.com/bazelbuild/bazel-watcher
@@ -53,33 +51,35 @@ new as of May 2017 and not very stable yet.
- Test all packages: `yarn test packages/...`
- Test angular.io app locally: `yarn test //aio/... --config=aio_local_deps`
-**Note**: The ellipsis in the last command above are not meant to be substituted by a package name, but
+The ellipsis in the examples above are not meant to be substituted by a package name, but
are used by Bazel as a wildcard to execute all tests in the specified path. To execute all the tests for a
single package, the commands are (exemplary):
- `yarn test //packages/core/...` for all tests, or
- `yarn test //packages/core/test:test` for a particular test suite.
-**Note**: The first test run will be much slower than future runs. This is because future runs will
-benefit from Bazel's capability to do incremental builds.
+Bazel very effectively caches build results, so it's common for your first time building a target
+to be much slower than subsequent builds.
-You can use [ibazel] to get a "watch mode" that continuously
+You can use [ibazel] to run in a "watch mode" that continuously
keeps the outputs up-to-date as you save sources.
-### Various Flags Used For Tests
+### Testing with flags
-If you're experiencing problems with seemingly unrelated tests failing, it may be because you're not using the proper flags with your Bazel test runs in Angular.
+If you're experiencing problems with seemingly unrelated tests failing, it may be because you're not
+using the proper flags with your Bazel test runs in Angular.
- `--config=debug`: build and launch in debug mode (see [debugging](#debugging) instructions below)
- `--test_arg=--node_options=--inspect=9228`: change the inspector port.
-- `--test_tag_filters=`: filter tests down to tags defined in the `tag` config of your rules in any given `BUILD.bazel`.
+- `--test_tag_filters=`: filter tests down to tags defined in the `tag` config of your rules in
+ any given `BUILD.bazel`.
-
-### Debugging a Node Test
+### Debugging a Node Test in Chrome DevTools
-- Open chrome at: [chrome://inspect](chrome://inspect)
+- Open Chrome at: [chrome://inspect](chrome://inspect)
- Click on `Open dedicated DevTools for Node` to launch a debugger.
-- Run test: `yarn bazel test packages/core/test:test --config=debug`
+- Run your test with the debug configuration,
+ e.g. `yarn bazel test packages/core/test:test --config=debug`
The process should automatically connect to the debugger.
For more, see the [rules_nodejs Debugging documentation](https://bazelbuild.github.io/rules_nodejs/index.html#debugging).
@@ -87,8 +87,12 @@ For more, see the [rules_nodejs Debugging documentation](https://bazelbuild.gith
For additional info and testing options, see the
[nodejs_test documentation](https://bazelbuild.github.io/rules_nodejs/Built-ins.html#nodejs_test).
-- Click on "Resume script execution" to let the code run until the first `debugger` statement or a previously set breakpoint.
-- If you're debugging a test and you want to inspect the generated template instructions, find the template of your component in the call stack and click on `(source mapped from [CompName].js)` at the bottom of the code. You can also disable sourcemaps in the options or go to sources and look into ng:// namespace to see all the generated code.
+- Click on "Resume script execution" to let the code run until the first `debugger` statement or a
+ previously set breakpoint.
+- If you want to inspect generated template instructions while debugging, find the
+ template of your component in the call stack and click on `(source mapped from [CompName].js)` at
+ the bottom of the code. You can also disable sourcemaps in Chrome DevTools' options or go to
+ sources and look into ng:// namespace to see all the generated code.
### Debugging a Node Test in VSCode
@@ -105,7 +109,8 @@ First time setup:
}
```
-**Setting breakpoints directly in your code files may not work in VSCode**. This is because the files you're actually debugging are built files that exist in a `./private/...` folder.
+**Setting breakpoints directly in your code files may not work in VSCode**. This is because the
+files you're actually debugging are built files that exist in a `./private/...` folder.
The easiest way to debug a test for now is to add a `debugger` statement in the code
and launch the bazel corresponding test (`yarn bazel test --config=debug`).
@@ -115,13 +120,17 @@ Apple+Shift+D on Mac) and click on the green play icon next to the configuration
### Debugging a Karma Test
-- Run test: `yarn bazel run packages/core/test:test_web_debug` (any `karma_web_test_suite` target has a `_debug` target)
+- Run test with `_debug` appended to the target name,
+ e.g. `yarn bazel run packages/core/test:test_web_debug`.
+ Every `karma_web_test_suite` target has an additional `_debug` target.
- Open any browser at: [http://localhost:9876/debug.html](http://localhost:9876/debug.html)
-- Open the browser's DevTools to debug the tests (after, for example, having focused on specific tests via `fit` and/or `fdescribe` or having added `debugger` statements in them)
+- Open the browser's DevTools to debug the tests (after, for example, having focused on specific
+ tests via `fit` and/or `fdescribe` or having added `debugger` statements in them)
### Debugging Bazel rules
-Open `external` directory which contains everything that bazel downloaded while executing the workspace file:
+Open `external` directory which contains everything that bazel downloaded while executing the
+workspace file:
```sh
open $(yarn -s bazel info output_base)/external
```
@@ -138,68 +147,69 @@ open $(yarn -s bazel info output_base)/external/build_bazel_rules_nodejs/interna
## Stamping
-Bazel supports the ability to include non-hermetic information from the version control system in built artifacts. This is called stamping.
+Bazel supports the ability to include non-hermetic information from the version control system in
+built artifacts. This is called stamping.
You can see an overview at https://www.kchodorow.com/blog/2017/03/27/stamping-your-builds/
-In our repo, here is how it's configured:
-1) In `tools/bazel_stamp_vars.js` we run the `git` commands to generate our versioning info.
-1) In `.bazelrc` we register this script as the value for the `workspace_status_command` flag. Bazel will run the script when it needs to stamp a binary.
+Angular configures stamping as follows:
-Note that Bazel has a `--stamp` argument to `yarn bazel build`, but this has no effect since our stamping takes place in Skylark rules. See https://github.com/bazelbuild/bazel/issues/1054
+1. In `tools/bazel_stamp_vars.js` we run the `git` commands to generate our versioning info.
+2. In `.bazelrc` we register this script as the value for the `workspace_status_command` flag. Bazel
+ will run the script when it needs to stamp a binary.
## Remote cache
-Bazel supports fetching action results from a cache, allowing a clean build to pick up artifacts from prior builds.
-This makes builds incremental, even on CI.
-It works because Bazel assigns a content-based hash to all action inputs, which is used as the cache key for the action outputs.
-Thanks to the hermeticity property, we can skip executing an action if the inputs hash is already present in the cache.
+Bazel supports fetching action results from a cache, allowing a clean build to reuse artifacts
+from prior builds. This makes builds incremental, even on CI.
-Of course, non-hermeticity in an action can cause problems.
-At worst, you can fetch a broken artifact from the cache, making your build non-reproducible.
-For this reason, we are careful to implement our Bazel rules to depend only on their inputs.
+Bazel assigns a content-based hash to all action inputs, which is used as the cache
+key for the action outputs. Because Bazel builds are hermetic, it can skip executing an action if
+the inputs hash is already present in the cache.
-Currently, we only use remote caching on CircleCI. We let Angular core developers enable remote caching to speed up their builds.
+When using this caching feature, non-hermetic actions cause problems. At worst, you can fetch a
+broken artifact from the cache, making your build non-reproducible. For this reason, we are careful
+to implement our Bazel rules to depend _exclusively_ on their inputs, never reading from the
+filesystem or the underlying environment directly.
+
+Currently, we only use remote caching on CI. Angular core developers can enable remote
+caching to speed up their builds.
### Remote cache in development
+Note: this is only available to Googlers
+
To enable remote caching for your build:
1. Go to the service accounts for the ["internal" project](https://console.cloud.google.com/iam-admin/serviceaccounts?project=internal-200822)
-1. Select "Angular local dev", click on "Edit", scroll to the bottom, and click "Create key"
-1. When the pop-up shows, select "JSON" for "Key type" and click "Create"
-1. Save the key in a secure location
-1. Create a file called `.bazelrc.user` in the root directory of the workspace, and add the following content:
+2. Select "Angular local dev", click on "Edit", scroll to the bottom, and click "Create key"
+3. When the pop-up shows, select "JSON" for "Key type" and click "Create"
+4. Save the key in a secure location
+5. Create a file called `.bazelrc.user` in the root directory of the workspace, and add the following content:
```
build --config=angular-team --google_credentials=[ABSOLUTE_PATH_TO_SERVICE_KEY]
```
-### Remote cache for Circle CI
-
-This feature is experimental, and developed by the CircleCI team with guidance from Angular.
-Contact Alex Eagle with questions.
-
-*How it's configured*:
-
-1. In `.circleci/config.yml`, each CircleCI job downloads a proxy binary, which is built from https://github.com/notnoopci/bazel-remote-proxy. The download is done by running `.circleci/setup_cache.sh`. When the feature graduates from experimental, this proxy will be installed by default on every CircleCI worker, and this step will not be needed.
-1. Next, each job runs the `setup-bazel-remote-cache` anchor. This starts up the proxy running in the background. In the CircleCI UI, you'll see this step continues running while later steps run, and you can see logging from the proxy process.
-1. Bazel must be configured to connect to the proxy on a local port. This configuration lives in `.circleci/bazel.linux.rc` and is enabled because we overwrite the system Bazel settings in /etc/bazel.bazelrc with this file.
-1. Each `bazel` command in `.circleci/config.yml` picks up and uses the caching flags.
-
## Diagnosing slow builds
If a build seems slow you can use Bazel to diagnose where time is spent.
-The first step is to generate a profile of the build using the `--profile filename_name.profile` flag.
+The first step is to generate a profile of the build using the `--profile filename_name.profile`
+flag.
+
```sh
yarn bazel build //packages/compiler --profile filename_name.profile
```
-This will generate a `filename_name.profile` that you can then analyse using [analyze-profile](https://docs.bazel.build/versions/master/user-manual.html#analyze-profile) command.
+This generates a `filename_name.profile` that you can then analyse
+using chrome://tracing or
+Bazel's [analyze-profile](https://docs.bazel.build/versions/master/user-manual.html#analyze-profile)
+command.
## Using the console profile report
You can obtain a simple report directly in the console by running:
+
```sh
yarn bazel analyze-profile filename_name.profile
```
@@ -238,22 +248,28 @@ A more comprehensive way to visualize the profile information is through the HTM
yarn bazel analyze-profile filename_name.profile --html --html_details --html_histograms
```
-This will generate a `filename_name.profile.html` file that you can open in your browser.
+This generates a `filename_name.profile.html` file that you can open in your browser.
-In the upper right corner that is a small table of contents with links to three areas: Tasks, Legend, and Statistics.
+In the upper right corner that is a small table of contents with links to three areas: Tasks,
+Legend, and Statistics.
-In the Tasks section you will find a graph of where time is spent. Legend shows what the colors in the Tasks graph mean.
-Hovering over the background will show what phase that is, while hovering over bars will show more details about that specific action.
+In the Tasks section you will find a graph of where time is spent. Legend shows what the colors in
+the Tasks graph mean.
+Hovering over the background will show what phase that is, while hovering over bars will show more
+details about that specific action.
The Statistics section shows how long each phase took and how time was spent in that phase.
Usually the longest one is the execution phase, which also includes critical path information.
-Also in the Statistics section are the Skylark statistic, split in User-Defined and Builtin function execution time.
-You can click the "self" header twice to order the table by functions where the most time (in ms) is spent.
-
-When diagnosing slow builds you should focus on the top time spenders across all phases and functions.
-Usually there is a single item (or multiple items of the same kind) where the overwhelming majority of time is spent.
+Also in the Statistics section are the Skylark statistic, split in User-Defined and Builtin function
+execution time.
+You can click the "self" header twice to order the table by functions where the most time (in ms) is
+spent.
+When diagnosing slow builds you should focus on the top time spenders across all phases and
+functions.
+Usually there is a single item (or multiple items of the same kind) where the overwhelming majority
+of time is spent.
## Known issues
diff --git a/contributing-docs/caretaking.md b/contributing-docs/caretaking.md
new file mode 100644
index 00000000000..31a2ff65399
--- /dev/null
+++ b/contributing-docs/caretaking.md
@@ -0,0 +1,49 @@
+# Caretaker
+
+The *caretaker* is a role responsible for merging PRs and syncing into Google's
+internal code repository. The caretaker role rotates weekly.
+
+## Responsibilities
+
+- Merging PR (PRs with [`action: merge`](https://github.com/angular/angular/pulls?q=is%3Aopen+is%3Apr+label%3A%22action%3A+merge%22) label)
+- Light issue triage [new issues](https://github.com/angular/angular/issues?q=is%3Aopen+is%3Aissue+no%3Alabel).
+
+## Merging the PR
+
+A PR requires the `action: merge` and a `target: *` label to be merged.
+
+The tooling automatically verifies the given PR is ready for merge. If the PR passes the tests, the
+tool will automatically merge it based on the applied target label.
+
+To merge a PR run:
+
+```sh
+$ yarn ng-dev pr merge
+```
+
+## Primitives and blocked merges
+
+Some directories in the Angular codebase have additional protections or rules. For example, code
+under `//packages/core/primitives` must be merged and synced into Google separately from other
+changes. Attempting to combine changes in `primitives` with other changes results in an error. This
+practices makes it significantly easier to rollback or revert changes in the event of a breakage or
+outage.
+
+## PRs that require global presubmits
+
+Most PRs are tested against a curated subset of Angular application tests inside Google. However,
+if a change is deemed risky or otherwise requires more thorough testing, add the `requires: TGP`
+label to the PR. For such PRs, the merge tooling enforces that _all_ affected tests inside Google
+have been run (a "global presubmit"). A Googler can alternatively satisfy the merge tooling check by
+adding a review comment that starts with `TESTED=` and then put a reason why the PR is sufficiently
+tested. The `requires: TGP` label is automatically added to PRs that affect files
+matching `separateFilePatterns` in [`.ng-dev/google-sync-config.json`](https://github.com/angular/angular/blob/main/.ng-dev/google-sync-config.json).
+
+An example of specfying a `TESTED=` comment:
+```
+TESTED=docs only update and does not need a TGP
+```
+
+### Recovering from failed `merge-pr` due to conflicts
+
+The `ng-dev pr merge` tool will automatically restore to the previous git state when a merge fails.
diff --git a/docs/CODING_STANDARDS.md b/contributing-docs/coding-standards.md
similarity index 92%
rename from docs/CODING_STANDARDS.md
rename to contributing-docs/coding-standards.md
index 3cb41b5ffe5..31e4fff5bb8 100644
--- a/docs/CODING_STANDARDS.md
+++ b/contributing-docs/coding-standards.md
@@ -168,6 +168,16 @@ Use `readonly` members wherever possible.
* Prefer *exact* names over short names (within reason). For example, `labelPosition` is better than
`align` because the former much more exactly communicates what the property means.
* Except for `@Input()` properties, use `is` and `has` prefixes for boolean properties / methods.
+* Name identifiers based on their responsibility. Names should capture what the code *does*,
+ not how it is used:
+
+ ```typescript
+ /** NO: */
+ class DefaultRouteReuseStrategy { }
+
+ /** YES: */
+ class NonStoringRouteReuseStrategy { }
+ ```
##### Observables
@@ -175,19 +185,19 @@ Don't suffix observables with `$`.
##### Classes
-Name classes based on their responsibility. Names should capture what the code *does*,
-not how it is used:
-```typescript
-/** NO: */
-class DefaultRouteReuseStrategy { }
+* Use PascalCase (aka UpperCamelCase).
+* Class names should not end in `Impl`.
-/** YES: */
-class NonStoringRouteReuseStrategy { }
-```
+##### Interfaces
-##### Methods
+* Do not prefix interfaces with `I`.
+* Do not suffix interfaces with `Interface`.
-The name of a method should capture the action performed *by* that method rather than
+##### Functions and methods
+
+Use camelCase (aka lowerCamelCase).
+
+The name of a function should capture the action performed *by* that method rather than
describing when the method will be called. For example:
```typescript
@@ -202,6 +212,10 @@ activateRipple() {
}
```
+##### Constants and injection tokens
+
+Use UPPER_SNAKE_CASE.
+
##### Test classes and examples
Give test classes and examples meaningful, descriptive names.
diff --git a/docs/TOOLS.md b/contributing-docs/debugging-tips.md
similarity index 87%
rename from docs/TOOLS.md
rename to contributing-docs/debugging-tips.md
index 6a8d3661425..0f2707cb62d 100644
--- a/docs/TOOLS.md
+++ b/contributing-docs/debugging-tips.md
@@ -1,7 +1,18 @@
-# Developer Tools for Angular
+# Debugging tips for developing on Angular
-Here you will find a collection of tools and tips for keeping your application
-perform well and contain fewer bugs.
+## Debugging tests
+
+The Angular project has comprehensive unit tests for the core packages and the tools.
+Packages are tested both in the browser (via Karma) and on the server (via node.js).
+Angular uses the Jasmine test framework.
+
+You can focus your debugging on one test at a time by changing that test to be
+defined using the `fit(...)` function, rather than `it(...)`. Moreover, it can be helpful
+to place a `debugger` statement in this `fit` clause to cause the debugger to stop when
+it hits this test.
+
+For instructions on debugging both Karma and node.js tests, see
+[Building with bazel](./building-with-bazel.md).
## Angular debug tools in the dev console
@@ -11,7 +22,7 @@ Ctrl + Shift + j.
### Enabling debug tools
-By default the debug tools are disabled. You can enable debug tools as follows:
+By default, the debug tools are disabled. You can enable debug tools as follows:
```typescript
import {ApplicationRef} from '@angular/core';
diff --git a/docs/DEV_PREVIEW_AND_EXPERIMENTAL.md b/contributing-docs/dev_preview_and_experimental.md
similarity index 100%
rename from docs/DEV_PREVIEW_AND_EXPERIMENTAL.md
rename to contributing-docs/dev_preview_and_experimental.md
diff --git a/docs/GITHUB_PROCESS.md b/contributing-docs/feature-request-consideration.md
similarity index 64%
rename from docs/GITHUB_PROCESS.md
rename to contributing-docs/feature-request-consideration.md
index 8663427fbeb..56d2f1b7f4c 100644
--- a/docs/GITHUB_PROCESS.md
+++ b/contributing-docs/feature-request-consideration.md
@@ -1,24 +1,9 @@
-
-# Automatic conversation locking
-Closed issues and pull requests are locked automatically after 30 days of inactivity.
-
-## I want to comment on a locked conversation, what should I do?
-When an issue has been closed and inactive for over 30 days, the original context is likely outdated.
-If you encounter a similar or related issue in the current version, please open a new issue and
-provide up-to-date reproduction instructions.
-
-## Why lock conversations?
-Automatically locking closed, inactive issues guides people towards filing new issues with updated
-context rather than commenting on a "resolved" issue that contains out-of-date or unrelated
-information. As an example, someone may comment "I'm still having this issue", but without
-providing any of the additional information the team needs to investigate.
-
+
# Feature request process
To manage the requests we receive at scale, we introduced automation in our feature request
-management process. After we triage an issue and we identify it as a feature request, it goes
-through several steps.
+management process. After we identify an issue as a feature request, it goes through several steps.
## Manual review
@@ -29,7 +14,8 @@ initiates a voting process.
## Voting phase
To include the community in the feature request process, we open voting for a fixed length of time.
-Anyone can cast a vote for the request with a thumbs-up (👍) reaction on the original issue description.
+Anyone can cast a vote for the request with a thumbs-up (👍) reaction on the original issue
+description.
When a feature request reaches 20 or more upvotes, we formally consider the feature request.
Alternatively, the bot closes the request.
diff --git a/docs/images/angular-ecosystem-logos.png b/contributing-docs/images/angular-ecosystem-logos.png
similarity index 100%
rename from docs/images/angular-ecosystem-logos.png
rename to contributing-docs/images/angular-ecosystem-logos.png
diff --git a/docs/images/feature-request-automation.png b/contributing-docs/images/feature-request-automation.png
similarity index 100%
rename from docs/images/feature-request-automation.png
rename to contributing-docs/images/feature-request-automation.png
diff --git a/docs/images/pr-base-branch-screenshot.png b/contributing-docs/images/pr-base-branch-screenshot.png
similarity index 100%
rename from docs/images/pr-base-branch-screenshot.png
rename to contributing-docs/images/pr-base-branch-screenshot.png
diff --git a/contributing-docs/public-api-surface.md b/contributing-docs/public-api-surface.md
new file mode 100644
index 00000000000..1d2d4677e45
--- /dev/null
+++ b/contributing-docs/public-api-surface.md
@@ -0,0 +1,114 @@
+# Supported public API surface of angular/angular code
+
+Angular's SemVer, release schedule, and deprecation policy applies to these npm packages:
+
+- `@angular/animations`
+- `@angular/common`
+- `@angular/core`
+- `@angular/elements`
+- `@angular/forms`
+- `@angular/platform-browser-dynamic`
+- `@angular/platform-browser`
+- `@angular/platform-server`
+- `@angular/router`
+- `@angular/service-worker`
+- `@angular/upgrade`
+
+The `@angular/compiler` package is explicitly excluded from this list. The compiler is a generally
+considered private/internal API and may change at any time. Only very specific use-cases, such as
+linters or IDE integration, require direct access to the compiler API. If you are
+working on this kind of integration, please reach out to us first.
+
+Additionally, only the command line usage (not direct use of APIs) of
+`@angular/compiler-cli` is covered.
+
+Within the supported packages, Angular keeps stable:
+
+- Symbols exported via the main entry point (e.g. `@angular/core`) and testing entry point (
+ e.g. `@angular/core/testing`). This applies to both runtime/JavaScript values and TypeScript
+ types.
+- Symbols exported via global namespace `ng` (e.g. `ng.core`)
+
+We explicitly consider the following to be _excluded_ from the public API:
+
+- Any file/import paths within our package except for the `/`, `/testing` and `/bundles/*` and other
+ documented package entry-points.
+- Constructors of injectable classes (services and directives). Use dependency injection to obtain
+ instances of these classes
+- Any class members or symbols marked as `private`, or prefixed with
+ underscore (`_`), [barred latin o](https://en.wikipedia.org/wiki/%C6%9F) (`ɵ`), and double barred latin o (`ɵɵ`).
+- Extending any of our classes unless the support for this is specifically documented in the API
+ reference.
+- The contents and API surface of the code generated by Angular's compiler.
+- The `@angular/core/primitives` package, including its descendant entry-points.
+
+Our peer dependencies (such as TypeScript, Zone.js, or RxJS) are not considered part of our API
+surface, but they are included in our SemVer policies. We might update the required version of these
+dependencies in minor releases if the update doesn't cause breaking changes for Angular
+applications. Peer dependency updates that result in non-trivial breaking changes must be deferred
+to major Angular releases.
+
+
+
+## Extending Angular classes
+
+All classes in Angular's public API are considered `final`. They should not be extended unless
+explicitly stated in the API documentation.
+
+Extending such classes is not supported, since protected members and internal implementation may
+change outside major releases.
+
+
+
+## Golden files
+
+Angular tracks the status of the public API in a *golden file*, maintained with a tool called the
+*public API guard*.
+If you modify any part of a public API in one of the supported public packages, the PR will fail a
+test in CI with an error message that instructs you to accept the golden file.
+
+The public API guard provides a Bazel target that updates the current status of a given package. If
+you add to or modify the public API in any way, you must use [yarn](https://yarnpkg.com/) to execute
+the Bazel target in your terminal shell of choice (a recent version of `bash` is recommended).
+
+```shell
+yarn bazel run //packages/:_api.accept
+```
+
+Here is an example of a CI test failure that resulted from adding a new allowed type to a public
+property in `core.d.ts`. Error messages from the API guard use [`git-diff` formatting](https://git-scm.com/docs/git-diff#_combined_diff_format).
+
+```
+FAIL: //packages/core:core_api (see /home/circleci/.cache/bazel/_bazel_circleci/9ce5c2144ecf75d11717c0aa41e45a8d/execroot/angular/bazel-out/k8-fastbuild/testlogs/packages/core/core_api/test_attempts/attempt_1.log)
+INFO: From Action packages/compiler-cli/ngcc/test/fesm5_angular_core.js:
+[BABEL] Note: The code generator has deoptimised the styling of /b/f/w/bazel-out/k8-fastbuild/bin/packages/core/npm_package/fesm2015/core.js as it exceeds the max of 500KB.
+FAIL: //packages/core:core_api (see /home/circleci/.cache/bazel/_bazel_circleci/9ce5c2144ecf75d11717c0aa41e45a8d/execroot/angular/bazel-out/k8-fastbuild/testlogs/packages/core/core_api/test.log)
+
+FAILED: //packages/core:core_api (Summary)
+ /home/circleci/.cache/bazel/_bazel_circleci/9ce5c2144ecf75d11717c0aa41e45a8d/execroot/angular/bazel-out/k8-fastbuild/testlogs/packages/core/core_api/test.log
+ /home/circleci/.cache/bazel/_bazel_circleci/9ce5c2144ecf75d11717c0aa41e45a8d/execroot/angular/bazel-out/k8-fastbuild/testlogs/packages/core/core_api/test_attempts/attempt_1.log
+INFO: From Testing //packages/core:core_api:
+==================== Test output for //packages/core:core_api:
+/b/f/w/bazel-out/k8-fastbuild/bin/packages/core/core_api.sh.runfiles/angular/packages/core/npm_package/core.d.ts(7,1): error: No export declaration found for symbol "ComponentFactory"
+--- goldens/public-api/core/core.d.ts Golden file
++++ goldens/public-api/core/core.d.ts Generated API
+@@ -563,9 +563,9 @@
+ ngModule: Type;
+ providers?: Provider[];
+ }
+
+-export declare type NgIterable = Array | Iterable;
++export declare type NgIterable = Iterable;
+
+ export declare interface NgModule {
+ bootstrap?: Array | any[]>;
+ declarations?: Array | any[]>;
+
+
+If you modify a public API, you must accept the new golden file.
+
+
+To do so, execute the following Bazel target:
+ yarn bazel run //packages/core:core_api.accept
+
+```
diff --git a/docs/BENCHMARKS.md b/contributing-docs/running-benchmarks.md
similarity index 91%
rename from docs/BENCHMARKS.md
rename to contributing-docs/running-benchmarks.md
index efc51fc3165..61655f58376 100644
--- a/docs/BENCHMARKS.md
+++ b/contributing-docs/running-benchmarks.md
@@ -31,5 +31,5 @@ You can start a comparison by adding a comment as followed to any PR:
/benchmark-compare //modules/benchmarks/src/expanding_rows:perf_chromium
```
-**Note**: An explicit benchmark target must be provided. You can use the prompt of `yarn benchmarks run` to
-discover available benchmarks.
+**Note**: An explicit benchmark target must be provided. You can use the prompt
+of `yarn benchmarks run` to discover available benchmarks.
diff --git a/docs/SAVED_REPLIES.md b/contributing-docs/saved-issue-replies.md
similarity index 90%
rename from docs/SAVED_REPLIES.md
rename to contributing-docs/saved-issue-replies.md
index 5574c4b6259..c35fbe53dc1 100644
--- a/docs/SAVED_REPLIES.md
+++ b/contributing-docs/saved-issue-replies.md
@@ -1,11 +1,15 @@
# Saved Responses for Angular's Issue Tracker
-The following are canned responses that the Angular team should use to close issues on our issue tracker that fall into the listed resolution categories.
-
-Since GitHub currently doesn't allow us to have a repository-wide or organization-wide list of [saved replies](https://help.github.com/articles/working-with-saved-replies/), these replies need to be maintained by individual team members. Since the responses can be modified in the future, all responses are versioned to simplify the process of keeping the responses up to date.
+This doc collects canned responses that the Angular team can use to close issues that fall into the
+listed resolution categories.
+Since GitHub currently doesn't allow us to have a repository-wide or organization-wide list
+of [saved replies](https://help.github.com/articles/working-with-saved-replies/), these replies need
+to be maintained by individual team members. Since the responses can be modified in the future, all
+responses are versioned to simplify the process of keeping the responses up to date.
## Angular: Already Fixed (v3)
+
```
Thanks for reporting this issue. Luckily it has already been fixed in one of the recent releases. Please update to the most recent version to resolve the problem.
@@ -13,6 +17,7 @@ If after upgrade the problem still exists in your application please [open a new
```
## Angular: Don't Understand (v3)
+
```
I'm sorry but we don't understand the problem you are reporting.
@@ -20,6 +25,7 @@ If the problem still exists in your application, please [open a new issue](https
```
## Angular: Can't reproduce (v2)
+
```
I'm sorry but we can't reproduce the problem you are reporting. We require that reported issues have a minimal reproduction that showcases the problem.
@@ -27,12 +33,13 @@ If the problem still exists in your application, please [open a new issue](https
```
## Angular: Duplicate (v2)
+
```
Thanks for reporting this issue. However this issue is a duplicate of an existing issue #ISSUE_NUMBER. Please subscribe to that issue for future updates.
```
-
## Angular: Insufficient Information Provided (v2)
+
```
Thanks for reporting this issue. However, you didn't provide sufficient information for us to understand and reproduce the problem. Please check out [our submission guidelines](https://github.com/angular/angular/blob/main/CONTRIBUTING.md#submit-issue) to understand why we can't act on issues that are lacking important information.
@@ -41,16 +48,19 @@ If the problem still exists in your application, please [open a new issue](https
```
## Angular: Issue Outside of Angular (v2)
+
```
I'm sorry but this issue is not caused by Angular. Please contact the author(s) of project PROJECT_NAME or file issue on their issue tracker.
```
## Angular: Behaving as Expected (v1)
+
```
It appears this behaves as expected. If you still feel there is an issue, please provide further details in a new issue.
```
## Angular: Non-reproducible (v2)
+
```
I'm sorry but we can't reproduce the problem following the instructions you provided.
@@ -58,14 +68,15 @@ If the problem still exists in your application please [open a new issue](https:
```
## Angular: Obsolete (v2)
+
```
Thanks for reporting this issue. This issue is now obsolete due to changes in the recent releases. Please update to the most recent Angular version.
If the problem still exists in your application, please [open a new issue](https://github.com/angular/angular/issues/new/choose) and follow the instructions in the issue template.
```
-
## Angular: Support Request (v1)
+
```
Hello, we reviewed this issue and determined that it doesn't fall into the bug report or feature request category. This issue tracker is not suitable for support requests, please repost your issue on [StackOverflow](https://stackoverflow.com/) using tag `angular`.
@@ -73,6 +84,7 @@ If you are wondering why we don't resolve support issues via the issue tracker,
```
## Angular: Commit Header
+
```
It looks like you need to update your commit header to match our requirements. This is different from the PR title. To update the commit header, use the command `git commit --amend` and update the header there.
@@ -80,6 +92,7 @@ Once you've finished that update, you will need to force push using `git push [o
```
## Angular: Rebase and Squash
+
```
Please rebase and squash your commits. To do this, make sure to `git fetch upstream` to get the latest changes from the angular repository. Then in your branch run `git rebase upstream/main -i` to do an interactive rebase. This should allow you to fixup or drop any unnecessary commits. After you finish the rebase, force push using `git push [origin name] [branch name] --force`.
```
diff --git a/docs/TRIAGE_AND_LABELS.md b/contributing-docs/triage-and-labelling.md
similarity index 51%
rename from docs/TRIAGE_AND_LABELS.md
rename to contributing-docs/triage-and-labelling.md
index 040b67beb5e..b11e1a46707 100644
--- a/docs/TRIAGE_AND_LABELS.md
+++ b/contributing-docs/triage-and-labelling.md
@@ -4,61 +4,24 @@ This document describes how the Angular team uses labels and milestones to triag
The basic idea of the process is that caretaker only assigns a component (`area: *`) label.
The owner of the component is then responsible for the detailed / component-level triage.
-
## Label Types
-### Components
+### Areas
-The caretaker should be able to determine which component the issue belongs to.
-The components have a clear piece of source code associated with it within the `/packages/` folder
-of this repo.
-
-* `area: animations`
-* `area: bazel` - @angular/bazel rules
-* `area: benchpress`
-* `area: common` - this includes core components / pipes
-* `area: common/http` - this includes core components / pipes
-* `area: core & compiler` - because core, compiler, compiler-cli and
- browser-platforms are very intertwined, we will be treating them as one
-* `area: ivy` - a subset of core representing the new Ivy renderer.
-* `area: ve` - a subset of `core & compiler` representing changes specific to ViewEngine (legacy compiler/renderer).
-* `area: docs-infra` - the angular.io application and docs-related tooling
-* `area: elements`
-* `area: forms`
-* `area: http`
-* `area: i18n`
-* `area: language-service`
-* `area: metadata-extractor`
-* `area: router`
-* `area: server`
-* `area: service-worker`
-* `area: testing`
-* `area: upgrade`
-* `area: web-worker`
-* `area: zones`
-
-There are few components which are cross-cutting.
-They don't have a clear location in the source tree.
-We will treat them as a component even thought no specific source tree is associated with them.
-
-* `area: build & ci` - build and CI infrastructure for the angular/angular repo
-* `area: dev-infra` - angular's common internal developer infrastructure scripting and tooling
-* `area: docs` - documentation, including API docs, guides, tutorial
-* `area: packaging` - packaging format of @angular/* npm packages
-* `area: performance`
-* `area: security`
-
-Sometimes, especially in the case of cross-cutting issues or PRs, these PRs or issues belong to
-multiple components. In these cases, all applicable component labels should be used to triage the
-issue or PR.
+The caretaker should be able to determine the _area_ for incoming issues.
+Most areas generally corresponds to a specific directory or set of directories in this repo. Some
+areas are more cross-cutting (e.g. for performance or security). Apply all labels that make sense
+for an issue. Each `area: ` label on GitHub should have a description of what it's for.
### Community engagement
-* `help wanted` - Indicates an issue whose complexity/scope makes it suitable for a community contributor to pick up.
+* `help wanted` - Indicates an issue whose complexity/scope makes it suitable for a community
+ contributor to pick up.
* `good first issue` - Indicates an issue that is suitable for first-time contributors.
(This label should be applied _in addition_ to `help wanted` for better discoverability.)
-`help wanted` and `good first issue` are [default GitHub labels] familiar to many developers.
+`help wanted` and `good first issue` are [default GitHub labels] familiar to many
+developers.
[default GitHub labels]: https://docs.github.com/en/github/managing-your-work-on-github/managing-labels#about-default-labels
@@ -73,11 +36,11 @@ resolve it.
Initial triage should occur daily so that issues can move into detailed triage.
-Once the initial triage is done, the ng-bot automatically adds the milestone `needs triage`.
+Once the initial triage is done, the ng-bot automatically adds the milestone `needsTriage`.
## Detailed Triage
-Detailed triage can be done by anyone familiar with the issue subject matter.
+Detailed triage can be done by anyone familiar with the issue's area.
### Step 1: Does the issue have enough information?
@@ -103,15 +66,14 @@ appropriate channel unless they're capturing a legitimate bug.
For bug reports, set a priority label.
-| Label | Description |
-|----|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| P0 | An issue that causes a full outage, breakage, or major function unavailability for everyone, without any known workaround. The issue must be fixed immediately, taking precedence over all other work. Should receive updates at least once per day. |
-| P1 | An issue that significantly impacts a large percentage of users; if there is a workaround it is partial or overly painful. The issue should be resolved before the next release. |
-| P2 | The issue is important to a large percentage of users, with a workaround. Issues that are significantly ugly or painful (especially first-use or install-time issues). Issues with workarounds that would otherwise be P0 or P1. |
-| P3 | An issue that is relevant to core functions, but does not impede progress. Important, but not urgent. |
-| P4 | A relatively minor issue that is not relevant to core functions, or relates only to the attractiveness or pleasantness of use of the system. Good to have but not necessary changes/fixes. |
-| P5 | The team acknowledges the request but (due to any number of reasons) does not plan to work on or accept contributions for this request. The issue remains open for discussion. |
-
+| Label | Description |
+|-------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| P0 | An issue that causes a full outage, breakage, or major function unavailability for everyone, without any known workaround. The issue must be fixed immediately, taking precedence over all other work. Should receive updates at least once per day. |
+| P1 | An issue that significantly impacts a large percentage of users; if there is a workaround it is partial or overly painful. The issue should be resolved before the next release. |
+| P2 | The issue is important to a large percentage of users, with a workaround. Issues that are significantly ugly or painful (especially first-use or install-time issues). Issues with workarounds that would otherwise be P0 or P1. |
+| P3 | An issue that is relevant to core functions, but does not impede progress. Important, but not urgent. |
+| P4 | A relatively minor issue that is not relevant to core functions, or relates only to the attractiveness or pleasantness of use of the system. Good to have but not necessary changes/fixes. |
+| P5 | The team acknowledges the request but (due to any number of reasons) does not plan to work on or accept contributions for this request. The issue remains open for discussion. |
Issues marked with "feature" or "discussion" don't require a priority.
@@ -128,40 +90,46 @@ they apply to the issue:
Once this triage is done, the ng-bot automatically changes the milestone from `needs triage` to
`Backlog`.
-
## Triaging PRs
PRs labels signal their state. Every triaged PR must have a `action: *` label assigned to it:
* `action: discuss`: Discussion is needed, to be led by the author.
- * _**Who adds it:** Typically the PR author._
- * _**Who removes it:** Whoever added it._
-* `action: review` (optional): One or more reviews are pending. The label is optional, since the review status can be derived from GitHub's Reviewers interface.
- * _**Who adds it:** Any team member. The caretaker can use it to differentiate PRs pending review from merge-ready PRs._
- * _**Who removes it:** Whoever added it or the reviewer adding the last missing review._
+ * _**Who adds it:** Typically the PR author._
+ * _**Who removes it:** Whoever added it._
+* `action: review` (optional): One or more reviews are pending. The label is optional, since the
+ review status can be derived from GitHub's Reviewers interface.
+ * _**Who adds it:** Any team member. The caretaker can use it to differentiate PRs pending
+ review from merge-ready PRs._
+ * _**Who removes it:** Whoever added it or the reviewer adding the last missing review._
* `action: cleanup`: More work is needed from the author.
- * _**Who adds it:** The reviewer requesting changes to the PR._
- * _**Who removes it:** Either the author (after implementing the requested changes) or the reviewer (after confirming the requested changes have been implemented)._
-* `action: merge`: The PR author is ready for the changes to be merged by the caretaker as soon as the PR is green (or merge-assistance label is applied and caretaker has deemed it acceptable manually). In other words, this label indicates to "auto submit when ready".
- * _**Who adds it:** Typically the PR author._
- * _**Who removes it:** Whoever added it._
-
+ * _**Who adds it:** The reviewer requesting changes to the PR._
+ * _**Who removes it:** Either the author (after implementing the requested changes) or the
+ reviewer (after confirming the requested changes have been implemented)._
+* `action: merge`: The PR author is ready for the changes to be merged by the caretaker as soon as
+ the PR is green (or merge-assistance label is applied and caretaker has deemed it acceptable
+ manually). In other words, this label indicates to "auto submit when ready".
+ * _**Who adds it:** Typically the PR author._
+ * _**Who removes it:** Whoever added it._
In addition, PRs can have the following states:
* `state: WIP`: PR is experimental or rapidly changing. Not ready for review or triage.
- * _**Who adds it:** The PR author._
- * _**Who removes it:** Whoever added it._
+ * _**Who adds it:** The PR author._
+ * _**Who removes it:** Whoever added it._
* `state: blocked`: PR is blocked on an issue or other PR. Not ready for merge.
- * _**Who adds it:** Any team member._
- * _**Who removes it:** Any team member._
+ * _**Who adds it:** Any team member._
+ * _**Who removes it:** Any team member._
When a PR is ready for review, a review should be requested using the Reviewers interface in GitHub.
-
## PR Target
-In our git workflow, we merge changes either to the `main` branch, the active patch branch (e.g. `5.0.x`), or to both.
+See [Branches and versioning](./branches-and-versioning.md) for background on how Angular
+manages its branches and versioning.
+
+In our git workflow, we merge changes either to the `main` branch, the active patch branch (
+e.g. `5.0.x`), or to both.
The decision about the target must be done by the PR author and/or reviewer.
This decision is then honored when the PR is being merged by the caretaker.
@@ -172,67 +140,86 @@ Targeting an active release train:
* `target: major`: Any breaking change
* `target: minor`: Any new feature
-* `target: patch`: Bug fixes, refactorings, documentation changes, etc. that pose no or very low risk of adversely
+* `target: patch`: Bug fixes, refactorings, documentation changes, etc. that pose no or very low
+ risk of adversely
affecting existing applications.
Special Cases:
-* `target: rc`: A critical fix for an active release-train while it is in a feature freeze or RC phase
-* `target: lts`: A critical fix for a specific release-train that is still within the long term support phase
+* `target: rc`: A critical fix for an active release-train while it is in a feature freeze or RC
+ phase
+* `target: lts`: A critical fix for a specific release-train that is still within the long term
+ support phase
Notes:
- - To land a change only in a patch/RC branch, without landing it in any other active release-train branch (such
+
+- To land a change only in a patch/RC branch, without landing it in any other active release-train
+ branch (such
as `main`), the patch/RC branch can be targeted in the GitHub UI with the appropriate
`target: patch`/`target: rc` label.
- - `target: lts` PRs must target the specific LTS branch they would need to merge into in the GitHub UI, in
- cases which a change is desired in multiple LTS branches, individual PRs for each LTS branch must be created
-
-
-If a PR is missing the `target:*` label, it will be marked as pending by the angular robot status checks.
+- `target: lts` PRs must target the specific LTS branch they would need to merge into in the GitHub
+ UI, in
+ cases which a change is desired in multiple LTS branches, individual PRs for each LTS branch must
+ be created
+If a PR is missing the `target:*` label, it will be marked as pending by the angular robot status
+checks.
## PR Approvals
Before a PR can be merged it must be approved by the appropriate reviewer(s).
-To ensure that the right people review each change, we set review requests using [PullApprove](https://docs.pullapprove.com/) (via `.pullapprove`) and require that each PR has at least one approval from an appropriate code owner.
+To ensure that the right people review each change, we set review requests
+using [PullApprove](https://docs.pullapprove.com/) (via `.pullapprove`) and require that each PR has
+at least one approval from an appropriate code owner.
-If the PR author is a code owner themselves, the approval can come from _any_ repo collaborator (person with write access).
+If the PR author is a code owner themselves, the approval can come from _any_ repo collaborator (
+person with write access).
In any case, the reviewer should actually look through the code and provide feedback if necessary.
Note that approved state does not mean a PR is ready to be merged.
-For example, a reviewer might approve the PR but request a minor tweak that doesn't need further review, e.g., a rebase or small uncontroversial change.
+For example, a reviewer might approve the PR but request a minor tweak that doesn't need further
+review, e.g., a rebase or small uncontroversial change.
Only the `action: merge` label means that the PR is ready for merging.
-
## Special Labels
### `cla: yes`, `cla: no`
-* _**Who adds it:** @googlebot, or a Googler manually overriding the status in case the bot got it wrong._
+
+* _**Who adds it:** @googlebot, or a Googler manually overriding the status in case the bot got it
+ wrong._
* _**Who removes it:** @googlebot._
Managed by googlebot.
Indicates whether a PR has a CLA on file for its author(s).
Only issues with `cla:yes` should be merged into main.
-### `aio: preview`
+### `adev: preview`
+
* _**Who adds it:** Any team member. (Typically the author or a reviewer.)_
* _**Who removes it:** Any team member. (Typically, whoever added it.)_
-Applying this label to a PR makes the angular.io preview available regardless of the author. [More info](../aio/aio-builds-setup/docs/overview--security-model.md)
+Applying this label to a PR makes the angular.dev preview available regardless of the
+author.
### `action: merge-assistance`
+
* _**Who adds it:** Any team member._
* _**Who removes it:** Any team member._
This label can be added to let the caretaker know that the PR needs special attention.
-There should always be a comment added to the PR to explain why the caretaker's assistance is needed.
-The comment should be formatted like this: `merge-assistance: `
+There should always be a comment added to the PR to explain why the caretaker's assistance is
+needed.
+The comment should be formatted like
+this: `merge-assistance: `
-For example, the PR owner might not be a Googler and needs help to run g3sync; or one of the checks is failing due to external causes and the PR should still be merged.
+For example, the PR owner might not be a Googler and needs help to run g3sync; or one of the checks
+is failing due to external causes and the PR should still be merged.
### `action: rerun CI at HEAD`
+
* _**Who adds it:** Any team member._
* _**Who removes it:** The Angular Bot, once it triggers the CI rerun._
-This label can be added to instruct the Angular Bot to rerun the CI jobs for the PR at latest HEAD of the branch it targets.
+This label can be added to instruct the Angular Bot to rerun the CI jobs for the PR at latest HEAD
+of the branch it targets.
diff --git a/docs/FIXUP_COMMITS.md b/contributing-docs/using-fixup-commits.md
similarity index 62%
rename from docs/FIXUP_COMMITS.md
rename to contributing-docs/using-fixup-commits.md
index 385c36115fc..e46eb21f738 100644
--- a/docs/FIXUP_COMMITS.md
+++ b/contributing-docs/using-fixup-commits.md
@@ -1,22 +1,27 @@
# Working with fixup commits
This document provides information and guidelines for working with fixup commits:
+
- [What are fixup commits](#about-fixup-commits)
- [Why use fixup commits](#why-fixup-commits)
- [Creating fixup commits](#create-fixup-commits)
- [Squashing fixup commits](#squash-fixup-commits)
-[This blog post](https://thoughtbot.com/blog/autosquashing-git-commits) is also a good resource on the subject.
-
+[This blog post](https://thoughtbot.com/blog/autosquashing-git-commits) is also a good resource on
+the subject.
## What are fixup commits
At their core, fixup commits are just regular commits with a special commit message:
-The first line of their commit message starts with "fixup! " (notice the space after "!") followed by the first line of the commit message of an earlier commit (it doesn't have to be the immediately preceding one).
+The first line of their commit message starts with "fixup! " (notice the space after "!") followed
+by the first line of the commit message of an earlier commit (it doesn't have to be the immediately
+preceding one).
The purpose of a fixup commit is to modify an earlier commit.
-I.e. it allows adding more changes in a new commit, but "marking" them as belonging to an earlier commit.
-`Git` provides tools to make it easy to squash fixup commits into the original commit at a later time (see [below](#squash-fixup-commits) for details).
+I.e. it allows adding more changes in a new commit, but "marking" them as belonging to an earlier
+commit.
+`Git` provides tools to make it easy to squash fixup commits into the original commit at a later
+time (see [below](#squash-fixup-commits) for details).
For example, let's assume you have added the following commits to your branch:
@@ -25,7 +30,8 @@ feat: first commit
fix: second commit
```
-If you want to add more changes to the first commit, you can create a new commit with the commit message:
+If you want to add more changes to the first commit, you can create a new commit with the commit
+message:
`fixup! feat: first commit`:
```
@@ -34,7 +40,6 @@ fix: second commit
fixup! feat: first commit
```
-
## Why use fixup commits
So, when are fixup commits useful?
@@ -42,21 +47,28 @@ So, when are fixup commits useful?
During the life of a Pull Request, a reviewer might request changes.
The Pull Request author can make the requested changes and submit them for another review.
Normally, these changes should be part of one of the original commits of the Pull Request.
-However, amending an existing commit with the changes makes it difficult for the reviewer to know exactly what has changed since the last time they reviewed the Pull Request.
+However, amending an existing commit with the changes makes it difficult for the reviewer to know
+exactly what has changed since the last time they reviewed the Pull Request.
Here is where fixup commits come in handy.
-By addressing review feedback in fixup commits, you make it very straight forward for the reviewer to see what are the new changes that need to be reviewed and verify that their earlier feedback has been addressed.
-This can save a lot of effort, especially on larger Pull Requests (where having to re-review _all_ the changes is pretty wasteful).
-
-When the time comes to merge the Pull Request into the repository, the merge script knows how to automatically squash fixup commits with the corresponding regular commits.
+By addressing review feedback in fixup commits, you make it very straight forward for the reviewer
+to see what are the new changes that need to be reviewed and verify that their earlier feedback has
+been addressed.
+This can save a lot of effort, especially on larger Pull Requests (where having to re-review _all_
+the changes is pretty wasteful).
+When the time comes to merge the Pull Request into the repository, the merge script knows how to
+automatically squash fixup commits with the corresponding regular commits.
## Creating fixup commits
-As mentioned [above](#about-fixup-commits), the only thing that differentiates a fixup commit from a regular commit is the commit message.
-You can create a fixup commit by specifying an appropriate commit message (i.e. `fixup! `).
+As mentioned [above](#about-fixup-commits), the only thing that differentiates a fixup commit from a
+regular commit is the commit message.
+You can create a fixup commit by specifying an appropriate commit message (
+i.e. `fixup! `).
-In addition, the `git` command-line tool provides an easy way to create a fixup commit via [git commit --fixup](https://git-scm.com/docs/git-commit#Documentation/git-commit.txt---fixupltcommitgt):
+In addition, the `git` command-line tool provides an easy way to create a fixup commit
+via [git commit --fixup](https://git-scm.com/docs/git-commit#Documentation/git-commit.txt---fixupltcommitgt):
```sh
# Create a fixup commit to fix up the last commit on the branch:
@@ -66,30 +78,34 @@ git commit --fixup HEAD ...
git commit --fixup ...
```
-
## Squashing fixup commits
As mentioned above, the merge script will automatically squash fixup commits.
However, sometimes you might want to manually squash a fixup commit.
-
### Rebasing to squash fixup commits
-The easiest way to re-order and squash any commit is via [rebasing interactively](https://git-scm.com/docs/git-rebase#_interactive_mode). You move a commit right after the one you want to squash it into in the rebase TODO list and change the corresponding action from `pick` to `fixup`.
+The easiest way to re-order and squash any commit is
+via [rebasing interactively](https://git-scm.com/docs/git-rebase#_interactive_mode). You move a
+commit right after the one you want to squash it into in the rebase TODO list and change the
+corresponding action from `pick` to `fixup`.
`Git` can do all these automatically for you if you pass the `--autosquash` option to `git rebase`.
-See the [`git` docs](https://git-scm.com/docs/git-rebase#Documentation/git-rebase.txt---autosquash) for more details.
-
+See the [`git` docs](https://git-scm.com/docs/git-rebase#Documentation/git-rebase.txt---autosquash)
+for more details.
### Additional options
You may like to consider some optional configurations:
-
#### Configuring `git` to auto-squash by default
By default, `git` will not automatically squash fixup commits when interactively rebasing.
-If you prefer to not have to pass the `--autosquash` option every time, you can change the default behavior by setting the `rebase.autoSquash` `git` config option to true.
-See the [`git` docs](https://git-scm.com/docs/git-rebase#Documentation/git-rebase.txt-rebaseautoSquash) for more details.
+If you prefer to not have to pass the `--autosquash` option every time, you can change the default
+behavior by setting the `rebase.autoSquash` `git` config option to true.
+See
+the [`git` docs](https://git-scm.com/docs/git-rebase#Documentation/git-rebase.txt-rebaseautoSquash)
+for more details.
-If you have `rebase.autoSquash` set to true, you can pass the `--no-autosquash` option to `git rebase` to override and disable this setting.
+If you have `rebase.autoSquash` set to true, you can pass the `--no-autosquash` option
+to `git rebase` to override and disable this setting.
diff --git a/docs/CARETAKER.md b/docs/CARETAKER.md
deleted file mode 100644
index cfc1deabe41..00000000000
--- a/docs/CARETAKER.md
+++ /dev/null
@@ -1,49 +0,0 @@
-# Caretaker
-
-Caretaker is responsible for merging PRs into the individual branches and internally at Google.
-
-## Responsibilities
-
-- Draining the queue of PRs ready to be merged. (PRs with [`action: merge`](https://github.com/angular/angular/pulls?q=is%3Aopen+is%3Apr+label%3A%22action%3A+merge%22) label)
-- Assigning [new issues](https://github.com/angular/angular/issues?q=is%3Aopen+is%3Aissue+no%3Alabel) to individual component authors.
-
-## Merging the PR
-
-A PR needs to have `action: merge` and `target: *` labels to be considered
-ready to merge. Merging is performed by running `ng-dev pr merge` with a PR number to merge.
-
-The tooling automatically verifies the given PR is ready for merge. If the PR passes the tests, the
-tool will automatically merge it based on the applied target label.
-
-To merge a PR run:
-
-```sh
-$ yarn ng-dev pr merge
-```
-
-## Primitives and Blocked merges
-
-The caretaker may encounter PRs that will fail to merge due to primitives files. Code inside some
-paths must be merged and synced separately. For example, anything under `//packages/core/primitives`
-has to be merged and synced separately from other changes. Once the latest sync has fully landed,
-merging can continue. This is to reduce the risk of challenging rollbacks in the event of a breakage.
-
-## PRs that require TGPs
-
-If a PR is risky or otherwise requires more thorough testing, add the `requires: TGP` label to the PR.
-The merge tooling will enforce that a TGP has been run, or alternatively you can add a review comment
-that starts with `TESTED=` and then put a reason why the PR is sufficiently tested. This will allow
-the PR to be merged. The `requires: TGP` label will be automatically added to PRs that affect files
-matching `separateFilePatterns` in [`.ng-dev/google-sync-config.json`](https://github.com/angular/angular/blob/main/.ng-dev/google-sync-config.json).
-
-For example:
-
-```
-TESTED=docs only update and does not need a TGP
-```
-
-**Note:** the review comment _must_ be made by a googler.
-
-### Recovering from failed `merge-pr` due to conflicts
-
-The `ng-dev pr merge` tool will automatically restore to the previous git state when a merge fails.
diff --git a/docs/COMMITTER.md b/docs/COMMITTER.md
deleted file mode 100644
index 6bae5141585..00000000000
--- a/docs/COMMITTER.md
+++ /dev/null
@@ -1,20 +0,0 @@
-# Pushing changes into the Angular tree
-
-Please see [Using git with Angular repositories](https://docs.google.com/document/d/1h8nijFSaa1jG_UE8v4WP7glh5qOUXnYtAtJh_gwOQHI/edit)
-for details about how we maintain a linear commit history and the rules for committing.
-
-As a contributor, see the instructions in [CONTRIBUTING.md](../CONTRIBUTING.md).
-
-# Change approvals
-
-Change approvals in our monorepo are managed via [PullApprove](https://docs.pullapprove.com/) and are configured via the [`.pullapprove.yml`](../.pullapprove.yml) file.
-
-# Merging
-
-Once a change has all of the required approvals, either the last approver or the PR author (if PR author has the project collaborator status)
-should mark the PR with the `action: merge` label and the correct [target label](https://github.com/angular/angular/blob/main/docs/TRIAGE_AND_LABELS.md#pr-target).
-This signals to the caretaker that the PR should be merged. See [merge instructions](CARETAKER.md).
-
-# Who is the Caretaker?
-
-See [this explanation](https://twitter.com/IgorMinar/status/799365744806854656).
diff --git a/docs/DEBUG.md b/docs/DEBUG.md
deleted file mode 100644
index b75c543d5f6..00000000000
--- a/docs/DEBUG.md
+++ /dev/null
@@ -1,24 +0,0 @@
-# Debugging Angular
-
-The Angular project has comprehensive unit tests for the core packages and the tools.
-The core packages are tested both in the browser (via Karma) and on the server (via Node.js).
-
-## Debugging in Karma
-
-It is useful to focus your debugging on one test at a time by changing that test to be
-defined using the `fit(...)` function, rather than `it(...)`. Moreover, it can be helpful
-to place a `debugger` statement in this `fit` clause to cause the debugger to stop when
-it hits this test.
-
-Read more about starting the debugger for Karma with Bazel in the [BAZEL.md](./BAZEL.md)
-document.
-
-## Debugging in Node
-
-It is useful to focus your debugging on one test at a time by changing that test to be
-defined using the `fit(...)` function, rather than `it(...)`. Moreover, it can be helpful
-to place a `debugger` statement in this `fit` clause to cause the debugger to stop when
-it hits this test.
-
-Read more about starting the debugger for NodeJS tests with Bazel in the [BAZEL.md](./BAZEL.md)
-document.
\ No newline at end of file
diff --git a/docs/NAMING.md b/docs/NAMING.md
deleted file mode 100644
index a04cdcf012e..00000000000
--- a/docs/NAMING.md
+++ /dev/null
@@ -1,32 +0,0 @@
-Naming Conventions in Angular
----
-
-In general Angular should follow TypeScript naming conventions.
-See: https://github.com/Microsoft/TypeScript/wiki/Coding-guidelines
-
-
-Classes:
- - Example: `Compiler`, `ApplicationMetadata`
- - Camel case with first letter uppercase
- - In general prefer single words. (This is so that when appending `Proto` or `Factory` the class
- is still reasonable to work with.)
- - Should not end with `Impl` or any other word which describes a specific implementation of an
- interface.
-
-
-Interfaces:
- - Follow the same rules as Classes
- - Should not have `I` or `Interface` in the name or any other way of identifying it as an interface.
-
-
-Methods and functions:
- - Example: `bootstrap`, `someMethod`
- - Should be camel case with first letter lowercase
-
-
-Constants:
- - Example: `CORE_DIRECTIVES`
- - Should be all uppercase with SNAKE_CASE
-
-
-
diff --git a/docs/PUBLIC_API.md b/docs/PUBLIC_API.md
deleted file mode 100644
index af1a99a983f..00000000000
--- a/docs/PUBLIC_API.md
+++ /dev/null
@@ -1,101 +0,0 @@
-# Supported Public API Surface of Angular
-
-Our semver, timed-release cycle and deprecation policy currently applies to these npm packages:
-
-- `@angular/animations`
-- `@angular/core`
-- `@angular/common`
-- `@angular/elements`
-- `@angular/forms`
-- `@angular/platform-browser`
-- `@angular/platform-browser-dynamic`
-- `@angular/platform-server`
-- `@angular/upgrade`
-- `@angular/router`
-- `@angular/service-worker`
-
-
-One intentional omission from this list is `@angular/compiler`, which is currently considered a low level API and is subject to internal changes. These changes will not affect any applications or libraries using the higher-level APIs (the command line interface or JIT compilation via `@angular/platform-browser-dynamic`). Only very specific use-cases, such as tooling integration for IDEs and linters, require direct access to the compiler API. If you are working on this kind of integration, please reach out to us first.
-
-Additionally only the command line usage (not direct use of APIs) of `@angular/compiler-cli` is covered.
-
-Other projects developed by the Angular team like angular-cli, Angular Material, will be covered by these or similar guarantees in the future as they mature.
-
-Within the supported packages, we provide guarantees for:
-
-- symbols exported via the main entry point (e.g. `@angular/core`) and testing entry point (e.g. `@angular/core/testing`). This applies to both runtime/JavaScript values and TypeScript types.
-- symbols exported via global namespace `ng` (e.g. `ng.core`)
-- bundles located in the `bundles/` directory of our npm packages (e.g. `@angular/core/bundles/core.umd.js`)
-
-
-We explicitly don't consider the following to be our public API surface:
-
-- any file/import paths within our package except for the `/`, `/testing` and `/bundles/*` and other documented package entry-points.
-- constructors of injectable classes (services and directives) - please use DI to obtain instances of these classes
-- any class members or symbols marked as `private`, or prefixed with underscore (`_`), [barred latin o](https://en.wikipedia.org/wiki/%C6%9F) (`ɵ`), and double barred latin o (`ɵɵ`).
-- extending any of our classes unless the support for this is specifically documented in the API docs
-- the contents and API surface of the code generated by Angular's compiler (with one notable exception: the existence and name of `NgModuleFactory` instances exported from generated code is guaranteed)
-- the `@angular/core/primitives` package, including its child entrypoints
-
-Our peer dependencies (such as TypeScript, Zone.js, or RxJS) are not considered part of our API surface, but they are included in our SemVer policies. We might update the required version of any of these dependencies in minor releases if the update doesn't cause breaking changes for Angular applications. Peer dependency updates that result in non-trivial breaking changes must be deferred to major Angular releases.
-
-
-
-## Extending Angular classes
-
-All classes in Angular's public API are `final` (they should not be extended) unless explicitly stated in the API documentation.
-
-Extending such `final` classes is not supported, since protected members and internal implementation may change outside of major releases.
-
-
-
-## Golden files
-
-Angular tracks the status of the public API in a *golden file*, maintained with a tool called the *public API guard*.
-If you modify any part of a public API in one of the supported public packages, the PR can fail a test in CI with an error message that instructs you to accept the golden file.
-
-The public API guard provides a Bazel target that updates the current status of a given package. If you add to or modify the public API in any way, you must use [yarn](https://yarnpkg.com/) to execute the Bazel target in your terminal shell of choice (a recent version of `bash` is recommended).
-
-```shell
-yarn bazel run //packages/:_api.accept
-```
-
-Using yarn ensures that you are running the correct version of Bazel.
-(Read more about building Angular with Bazel [here](./BAZEL.md).)
-
-Here is an example of a Circle CI test failure that resulted from adding a new allowed type to a public property in `core.d.ts`. Error messages from the API guard use [`git-diff` formatting](https://git-scm.com/docs/git-diff#_combined_diff_format).
-
-```
-FAIL: //packages/core:core_api (see /home/circleci/.cache/bazel/_bazel_circleci/9ce5c2144ecf75d11717c0aa41e45a8d/execroot/angular/bazel-out/k8-fastbuild/testlogs/packages/core/core_api/test_attempts/attempt_1.log)
-INFO: From Action packages/compiler-cli/ngcc/test/fesm5_angular_core.js:
-[BABEL] Note: The code generator has deoptimised the styling of /b/f/w/bazel-out/k8-fastbuild/bin/packages/core/npm_package/fesm2015/core.js as it exceeds the max of 500KB.
-FAIL: //packages/core:core_api (see /home/circleci/.cache/bazel/_bazel_circleci/9ce5c2144ecf75d11717c0aa41e45a8d/execroot/angular/bazel-out/k8-fastbuild/testlogs/packages/core/core_api/test.log)
-
-FAILED: //packages/core:core_api (Summary)
- /home/circleci/.cache/bazel/_bazel_circleci/9ce5c2144ecf75d11717c0aa41e45a8d/execroot/angular/bazel-out/k8-fastbuild/testlogs/packages/core/core_api/test.log
- /home/circleci/.cache/bazel/_bazel_circleci/9ce5c2144ecf75d11717c0aa41e45a8d/execroot/angular/bazel-out/k8-fastbuild/testlogs/packages/core/core_api/test_attempts/attempt_1.log
-INFO: From Testing //packages/core:core_api:
-==================== Test output for //packages/core:core_api:
-/b/f/w/bazel-out/k8-fastbuild/bin/packages/core/core_api.sh.runfiles/angular/packages/core/npm_package/core.d.ts(7,1): error: No export declaration found for symbol "ComponentFactory"
---- goldens/public-api/core/core.d.ts Golden file
-+++ goldens/public-api/core/core.d.ts Generated API
-@@ -563,9 +563,9 @@
- ngModule: Type;
- providers?: Provider[];
- }
-
--export declare type NgIterable = Array | Iterable;
-+export declare type NgIterable = Iterable;
-
- export declare interface NgModule {
- bootstrap?: Array | any[]>;
- declarations?: Array | any[]>;
-
-
-If you modify a public API, you must accept the new golden file.
-
-
-To do so, execute the following Bazel target:
- yarn bazel run //packages/core:core_api.accept
-
-```
diff --git a/docs/RELEASE_SCHEDULE.md b/docs/RELEASE_SCHEDULE.md
deleted file mode 100644
index ee976eb9026..00000000000
--- a/docs/RELEASE_SCHEDULE.md
+++ /dev/null
@@ -1,6 +0,0 @@
-# Angular Release Schedule
-
-The Angular release schedule has moved.
-
-See [Angular releases](https://angular.io/guide/releases "Angular releases") for information about release policies and practices—including deprecation and support practices—as well as estimated dates for our next major releases.
-