docs: update and reorganize contributor docs (angular#56141)

* Move from `docs/` to `contributing-docs/`
* Updated file names to better communicate their content
* Consolidated content into fewer docs
* Updated and/or deleted obsolete info

PR Close angular#56141

Author: jelbourn

.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',

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].
 
 
 ## <a name="issue"></a> 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).
 
 
 ## <a name="commit"></a> 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

contributing-docs/auto-issue-locking.md

@@ -0,0 +1,19 @@
+<a name="conversation-locking"></a>
+
+# 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.

docs/BRANCHES.md contributing-docs/branches-and-versioning.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.
 
-<a name="formatting-your-source-code">
+<a name="formatting-your-source-code"></a>
 <a name="clang-format"></a>
 <a name="prettier"></a>
 
@@ -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 <path-to-local-project-root>
 ```
@@ -108,11 +117,17 @@ yarn ng-dev misc build-and-link <path-to-local-project-root>
 
 #### 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 <files..>`: format only provided files
 
@@ -138,59 +155,17 @@ $ 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.
 
 You may find that your un-merged change needs some validation from external participants.
 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 `<package-name>-pr<pr-number>-<sha>.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<pr-number>-<sha>.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.