Merging upstream version 1.70.0+dfsg1.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

42 files changed, 1041 insertions, 798 deletions

diff --git a/src/doc/rustc-dev-guide/.github/workflows/ci.yml b/src/doc/rustc-dev-guide/.github/workflows/ci.yml
index 2346698d4..bb0493bf7 100644
--- a/src/doc/rustc-dev-guide/.github/workflows/ci.yml
+++ b/src/doc/rustc-dev-guide/.github/workflows/ci.yml
@@ -46,7 +46,7 @@ jobs:
         if: github.event_name != 'push'
         run: |
           shopt -s globstar
-          MAX_LINE_LENGTH=100 bash ci/check_line_lengths.sh src/**/*.md
+          MAX_LINE_LENGTH=100 bash ci/lengthcheck.sh src/**/*.md
 
       - name: Install latest nightly Rust toolchain
         if: steps.mdbook-cache.outputs.cache-hit != 'true'
diff --git a/src/doc/rustc-dev-guide/README.md b/src/doc/rustc-dev-guide/README.md
index e501c9161..fdf6c5050 100644
--- a/src/doc/rustc-dev-guide/README.md
+++ b/src/doc/rustc-dev-guide/README.md
@@ -49,10 +49,10 @@ To build a local static HTML site, install [`mdbook`](https://github.com/rust-la
 and execute the following command in the root of the repository:
 
 ```
-> mdbook build
+> mdbook build --open
 ```
 
-The build files are found in the `book` directory.
+The build files are found in the `book/html` directory.
 
 ### Link Validations
 
@@ -67,20 +67,20 @@ including the `<!-- toc -->` marker at the place where you want the TOC.
 ### Pre-commit script
 
 We also test that line lengths are less than 100 columns. To test this locally,
-you can run `ci/check_line_lengths.sh`.
+you can run `ci/lengthcheck.sh`.
 
 You can also set this to run automatically.
 
 On Linux:
 
 ```bash
-ln -s ../../ci/check_line_lengths.sh .git/hooks/pre-commit
+ln -s ../../ci/lengthcheck.sh .git/hooks/pre-commit
 ```
 
 On Windows:
 
 ```powershell
-New-Item -Path .git/hooks/pre-commit -ItemType HardLink -Value <absolute_path/to/check_line_lengths.sh>
+New-Item -Path .git/hooks/pre-commit -ItemType HardLink -Value $(Resolve-Path ci/lengthcheck.sh)
 ```
 
 ## How to fix toolstate failures
diff --git a/src/doc/rustc-dev-guide/book.toml b/src/doc/rustc-dev-guide/book.toml
index a5d794b50..203bfd61e 100644
--- a/src/doc/rustc-dev-guide/book.toml
+++ b/src/doc/rustc-dev-guide/book.toml
@@ -43,10 +43,8 @@ exclude = [
 cache-timeout = 86400
 warning-policy = "error"
 
-[output.linkcheck.http-headers]
-'github\.com' = ["Authorization: Bearer $GITHUB_TOKEN"]
-
 [output.html.redirect]
 "/compiletest.html" = "tests/compiletest.html"
-"/diagnostics/sessiondiagnostic.html" = "diagnostics/diagnostic-structs.html"
+"/diagnostics/sessiondiagnostic.html" = "diagnostic-structs.html"
+"/diagnostics/diagnostic-codes.html" = "error-codes.html"
 "/miri.html" = "const-eval/interpret.html"
diff --git a/src/doc/rustc-dev-guide/ci/check_line_lengths.sh b/src/doc/rustc-dev-guide/ci/lengthcheck.sh
index 31cda5c65..76d677be7 100755
--- a/src/doc/rustc-dev-guide/ci/check_line_lengths.sh
+++ b/src/doc/rustc-dev-guide/ci/lengthcheck.sh
@@ -1,5 +1,7 @@
 #!/usr/bin/env bash
 
+# Check files for lines that are too long.
+
 if [ "$1" == "--help" ]; then
   echo 'Usage:' "[MAX_LINE_LENGTH=n] $0 [file ...]"
   exit 1
@@ -10,8 +12,7 @@ if [ "$MAX_LINE_LENGTH" == "" ]; then
 fi
 
 if [ "$1" == "" ]; then
-  shopt -s globstar
-  files=( src/**/*.md )
+  files=( src/*.md src/*/*.md src/*/*/*.md )
 else
   files=( "$@" )
 fi
@@ -22,7 +23,6 @@ echo "Offending files and lines:"
 (( bad_lines = 0 ))
 (( inside_block = 0 ))
 for file in "${files[@]}"; do
-  echo "$file"
   (( line_no = 0 ))
   while IFS="" read -r line || [[ -n "$line" ]] ; do
     (( line_no++ ))
@@ -34,7 +34,7 @@ for file in "${files[@]}"; do
         && ! [[ "$line" =~ " | "|"-|-"|"://"|"]:"|\[\^[^\ ]+\]: ]] \
         && (( "${#line}" > $MAX_LINE_LENGTH )) ; then
       (( bad_lines++ ))
-      echo -e "\t$line_no : $line"
+      echo -e "\t$file:$line_no : $line"
     fi
   done < "$file"
 done
diff --git a/src/doc/rustc-dev-guide/ci/linkcheck.sh b/src/doc/rustc-dev-guide/ci/linkcheck.sh
index 5d49d1337..133e22239 100755
--- a/src/doc/rustc-dev-guide/ci/linkcheck.sh
+++ b/src/doc/rustc-dev-guide/ci/linkcheck.sh
@@ -3,12 +3,16 @@
 set -e
 set -o pipefail
 
+set_github_token() {
+  jq '.config.output.linkcheck."http-headers"."github\\.com" = ["Authorization: Bearer $GITHUB_TOKEN"]'
+}
+
 # https://docs.github.com/en/actions/reference/environment-variables
 if [ "$GITHUB_EVENT_NAME" = "schedule" ] ; then # running in scheduled job
   FLAGS=""
+  USE_TOKEN=1
 
   echo "Doing full link check."
-  set -x
 elif [ "$GITHUB_EVENT_NAME" = "pull_request" ] ; then # running in PR CI build
   if [ -z "$BASE_SHA" ]; then
     echo "error: unexpected state: BASE_SHA must be non-empty in CI"
@@ -17,9 +21,9 @@ elif [ "$GITHUB_EVENT_NAME" = "pull_request" ] ; then # running in PR CI build
 
   CHANGED_FILES=$(git diff --name-only $BASE_SHA... | tr '\n' ' ')
   FLAGS="--no-cache -f $CHANGED_FILES"
+  USE_TOKEN=1
 
   echo "Checking files changed since $BASE_SHA: $CHANGED_FILES"
-  set -x
 else # running locally
   COMMIT_RANGE=master...
   CHANGED_FILES=$(git diff --name-only $COMMIT_RANGE | tr '\n' ' ')
@@ -28,4 +32,10 @@ else # running locally
   echo "Checking files changed in $COMMIT_RANGE: $CHANGED_FILES"
 fi
 
-exec mdbook-linkcheck $FLAGS
+echo "exec mdbook-linkcheck $FLAGS"
+if [ "$USE_TOKEN" = 1 ]; then
+  config=$(set_github_token)
+  exec mdbook-linkcheck $FLAGS <<<"$config"
+else
+  exec mdbook-linkcheck $FLAGS
+fi
diff --git a/src/doc/rustc-dev-guide/examples/rustc-driver-example.rs b/src/doc/rustc-dev-guide/examples/rustc-driver-example.rs
index 9708ab01d..70e77fd5b 100644
--- a/src/doc/rustc-dev-guide/examples/rustc-driver-example.rs
+++ b/src/doc/rustc-dev-guide/examples/rustc-driver-example.rs
@@ -42,9 +42,10 @@ fn main() {
 "#
             .into(),
         },
-        output_dir: None,                // Option<PathBuf>
-        output_file: None,               // Option<PathBuf>
-        file_loader: None,               // Option<Box<dyn FileLoader + Send + Sync>>
+        output_dir: None,  // Option<PathBuf>
+        output_file: None, // Option<PathBuf>
+        file_loader: None, // Option<Box<dyn FileLoader + Send + Sync>>
+        locale_resources: rustc_driver::DEFAULT_LOCALE_RESOURCES,
         lint_caps: FxHashMap::default(), // FxHashMap<lint::LintId, lint::Level>
         // This is a callback from the driver that is called when [`ParseSess`] is created.
         parse_sess_created: None, //Option<Box<dyn FnOnce(&mut ParseSess) + Send>>
diff --git a/src/doc/rustc-dev-guide/examples/rustc-driver-getting-diagnostics.rs b/src/doc/rustc-dev-guide/examples/rustc-driver-getting-diagnostics.rs
index 5bc2312a2..888674aaf 100644
--- a/src/doc/rustc-dev-guide/examples/rustc-driver-getting-diagnostics.rs
+++ b/src/doc/rustc-dev-guide/examples/rustc-driver-getting-diagnostics.rs
@@ -66,6 +66,7 @@ fn main() {
         output_dir: None,
         output_file: None,
         file_loader: None,
+        locale_resources: rustc_driver::DEFAULT_LOCALE_RESOURCES,
         lint_caps: rustc_hash::FxHashMap::default(),
         parse_sess_created: None,
         register_lints: None,
diff --git a/src/doc/rustc-dev-guide/examples/rustc-driver-interacting-with-the-ast.rs b/src/doc/rustc-dev-guide/examples/rustc-driver-interacting-with-the-ast.rs
index 53f8df81a..df0e0385d 100644
--- a/src/doc/rustc-dev-guide/examples/rustc-driver-interacting-with-the-ast.rs
+++ b/src/doc/rustc-dev-guide/examples/rustc-driver-interacting-with-the-ast.rs
@@ -44,6 +44,7 @@ fn main() {
         output_dir: None,
         output_file: None,
         file_loader: None,
+        locale_resources: rustc_driver::DEFAULT_LOCALE_RESOURCES,
         lint_caps: rustc_hash::FxHashMap::default(),
         parse_sess_created: None,
         register_lints: None,
diff --git a/src/doc/rustc-dev-guide/src/SUMMARY.md b/src/doc/rustc-dev-guide/src/SUMMARY.md
index adc397fd8..b01cb6797 100644
--- a/src/doc/rustc-dev-guide/src/SUMMARY.md
+++ b/src/doc/rustc-dev-guide/src/SUMMARY.md
@@ -1,8 +1,7 @@
 # Summary
 
-[About this guide](./about-this-guide.md)
-
 [Getting Started](./getting-started.md)
+[About this guide](./about-this-guide.md)
 
 ---
 
@@ -35,17 +34,19 @@
 
 # Contributing to Rust
 
-- [Introduction](./contributing.md)
+- [Contribution Procedures](./contributing.md)
 - [About the compiler team](./compiler-team.md)
 - [Using Git](./git.md)
 - [Mastering @rustbot](./rustbot.md)
 - [Walkthrough: a typical contribution](./walkthrough.md)
-- [Bug Fix Procedure](./bug-fix-procedure.md)
+- [Procedures for Breaking Changes](./bug-fix-procedure.md)
 - [Implementing new features](./implementing_new_features.md)
 - [Stability attributes](./stability.md)
 - [Stabilizing Features](./stabilization_guide.md)
 - [Feature Gates](./feature-gates.md)
 - [Coding conventions](./conventions.md)
+- [Using external repositories](./external-repos.md)
+- [Fuzzing](./fuzzing.md)
 - [Notification groups](notification-groups/about.md)
     - [ARM](notification-groups/arm.md)
     - [Cleanup Crew](notification-groups/cleanup-crew.md)
@@ -146,7 +147,7 @@
     - [Diagnostic and subdiagnostic structs](./diagnostics/diagnostic-structs.md)
     - [Translation](./diagnostics/translation.md)
     - [`LintStore`](./diagnostics/lintstore.md)
-    - [Diagnostic codes](./diagnostics/diagnostic-codes.md)
+    - [Error codes](./diagnostics/error-codes.md)
     - [Diagnostic items](./diagnostics/diagnostic-items.md)
     - [`ErrorGuaranteed`](./diagnostics/error-guaranteed.md)
 
diff --git a/src/doc/rustc-dev-guide/src/about-this-guide.md b/src/doc/rustc-dev-guide/src/about-this-guide.md
index 71407854e..944ebf5a8 100644
--- a/src/doc/rustc-dev-guide/src/about-this-guide.md
+++ b/src/doc/rustc-dev-guide/src/about-this-guide.md
@@ -58,14 +58,51 @@ please see the corresponding [subsection on writing documentation in this guide]
 
 You might also find the following sites useful:
 
-- [rustc API docs] -- rustdoc documentation for the compiler
+- This guide contains information about how various parts of the
+  compiler work and how to contribute to the compiler.
+- [rustc API docs] -- rustdoc documentation for the compiler, devtools, and internal tools
 - [Forge] -- contains documentation about Rust infrastructure, team procedures, and more
 - [compiler-team] -- the home-base for the Rust compiler team, with description
   of the team procedures, active working groups, and the team calendar.
 - [std-dev-guide] -- a similar guide for developing the standard library.
+- [The t-compiler zulip][z]
+- [The Forge](https://forge.rust-lang.org/) has more documentation about various procedures.
+- `#contribute` and `#wg-rustup` on [Discord](https://discord.gg/rust-lang).
+- The [Rust Internals forum][rif], a place to ask questions and
+  discuss Rust's internals
+- The [Rust reference][rr], even though it doesn't specifically talk about
+  Rust's internals, is a great resource nonetheless
+- Although out of date, [Tom Lee's great blog article][tlgba] is very helpful
+- [rustaceans.org][ro] is helpful, but mostly dedicated to IRC
+- The [Rust Compiler Testing Docs][rctd]
+- For [@bors], [this cheat sheet][cheatsheet] is helpful
+- Google is always helpful when programming.
+  You can [search all Rust documentation][gsearchdocs] (the standard library,
+  the compiler, the books, the references, and the guides) to quickly find
+  information about the language and compiler.
+- You can also use Rustdoc's built-in search feature to find documentation on
+  types and functions within the crates you're looking at. You can also search
+  by type signature! For example, searching for `* -> vec` should find all
+  functions that return a `Vec<T>`.
+  _Hint:_ Find more tips and keyboard shortcuts by typing `?` on any Rustdoc
+  page!
 
+
+[rustc dev guide]: about-this-guide.md
+[gsearchdocs]: https://www.google.com/search?q=site:doc.rust-lang.org+your+query+here
+[stddocs]: https://doc.rust-lang.org/std
+[rif]: http://internals.rust-lang.org
+[rr]: https://doc.rust-lang.org/book/README.html
+[rustforge]: https://forge.rust-lang.org/
+[tlgba]: https://tomlee.co/2014/04/a-more-detailed-tour-of-the-rust-compiler/
+[ro]: https://www.rustaceans.org/
+[rctd]: tests/intro.md
+[cheatsheet]: https://bors.rust-lang.org/
+[Miri]: https://github.com/rust-lang/miri
+[@bors]: https://github.com/bors
 [GitHub repository]: https://github.com/rust-lang/rustc-dev-guide/
-[rustc API docs]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/
+[rustc API docs]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle
 [Forge]: https://forge.rust-lang.org/
 [compiler-team]: https://github.com/rust-lang/compiler-team/
 [std-dev-guide]: https://std-dev-guide.rust-lang.org/
+[z]: https://rust-lang.zulipchat.com/#narrow/stream/131828-t-compiler
diff --git a/src/doc/rustc-dev-guide/src/backend/libs-and-metadata.md b/src/doc/rustc-dev-guide/src/backend/libs-and-metadata.md
index 5e005c965..b92a40b8b 100644
--- a/src/doc/rustc-dev-guide/src/backend/libs-and-metadata.md
+++ b/src/doc/rustc-dev-guide/src/backend/libs-and-metadata.md
@@ -103,9 +103,8 @@ The hash includes a variety of elements:
 * Hashes of the HIR nodes.
 * All of the upstream crate hashes.
 * All of the source filenames.
-* Hashes of certain command-line flags (like `-C metadata` via the [Crate
-  Disambiguator](#crate-disambiguator), and all CLI options marked with
-  `[TRACKED]`).
+* Hashes of certain command-line flags (like `-C metadata` via the [Stable
+  Crate Id](#stable-crate-id), and all CLI options marked with `[TRACKED]`).
 
 See [`compute_hir_hash`] for where the hash is actually computed.
 
diff --git a/src/doc/rustc-dev-guide/src/backend/monomorph.md b/src/doc/rustc-dev-guide/src/backend/monomorph.md
index cbc56acfc..7726daf4f 100644
--- a/src/doc/rustc-dev-guide/src/backend/monomorph.md
+++ b/src/doc/rustc-dev-guide/src/backend/monomorph.md
@@ -99,7 +99,7 @@ are relatively rare in functions, but closures inherit the generic
 parameters of their parent function and it is common for closures to not
 use those inherited parameters. Without polymorphization, a copy of these
 closures would be created for each copy of the parent function. By
-creating fewer copies, less LLVM IR is generated and needs processed.
+creating fewer copies, less LLVM IR is generated; therefore less needs to be processed.
 
 `unused_generic_params` returns a `FiniteBitSet<u64>` where a bit is set if
 the generic parameter of the corresponding index is unused. Any parameters
diff --git a/src/doc/rustc-dev-guide/src/bug-fix-procedure.md b/src/doc/rustc-dev-guide/src/bug-fix-procedure.md
index 2f5e24716..e69ce48f9 100644
--- a/src/doc/rustc-dev-guide/src/bug-fix-procedure.md
+++ b/src/doc/rustc-dev-guide/src/bug-fix-procedure.md
@@ -1,4 +1,4 @@
-# Rustc Bug Fix Procedure
+# Procedures for Breaking Changes
 
 <!-- toc -->
 
@@ -169,6 +169,13 @@ there were no errors before.
 
 #### Crater and crates.io
 
+[Crater] is a bot that will compile all crates.io crates and many
+public github repos with the compiler with your changes. A report will then be
+generated with crates that ceased to compile with or began to compile with your
+changes. Crater runs can take a few days to complete.
+
+[Crater]: ./tests/crater.md
+
 We should always do a crater run to assess impact. It is polite and considerate
 to at least notify the authors of affected crates the breaking change. If we can
 submit PRs to fix the problem, so much the better.
diff --git a/src/doc/rustc-dev-guide/src/building/bootstrapping.md b/src/doc/rustc-dev-guide/src/building/bootstrapping.md
index fe34cb500..d53896f81 100644
--- a/src/doc/rustc-dev-guide/src/building/bootstrapping.md
+++ b/src/doc/rustc-dev-guide/src/building/bootstrapping.md
@@ -22,6 +22,13 @@ Note that this documentation mostly covers user-facing information. See
 
 ## Stages of bootstrapping
 
+### Overview
+
+- Stage 0: the pre-compiled compiler
+- Stage 1: from current code, by an earlier compiler
+- Stage 2: the truly current compiler
+- Stage 3: the same-result test
+
 Compiling `rustc` is done in stages. Here's a diagram, adapted from Joshua Nelson's
 [talk on bootstrapping][rustconf22-talk] at RustConf 2022, with detailed explanations below.
 
@@ -51,7 +58,7 @@ graph TD
     classDef with-s1c fill: lightgreen;
 ```
 
-### Stage 0
+### Stage 0: the pre-compiled compiler
 
 The stage0 compiler is usually the current _beta_ `rustc` compiler
 and its associated dynamic libraries,
@@ -65,11 +72,11 @@ a compiler (with its set of dependencies)
 and its 'target' or 'object' libraries (`std` and `rustc`).
 Both are staged, but in a staggered manner.
 
-### Stage 1
+### Stage 1: from current code, by an earlier compiler
 
 The rustc source code is then compiled with the stage0 compiler to produce the stage1 compiler.
 
-### Stage 2
+### Stage 2: the truly current compiler
 
 We then rebuild our stage1 compiler with itself to produce the stage2 compiler.
 
@@ -92,7 +99,7 @@ For development, you usually only want the `stage1` compiler,
 which you can build with `./x.py build library`.
 See [Building the compiler](./how-to-build-and-run.html#building-the-compiler).
 
-### Stage 3
+### Stage 3: the same-result test
 
 Stage 3 is optional. To sanity check our new compiler, we
 can build the libraries with the stage2 compiler. The result ought
@@ -249,6 +256,10 @@ So the stage2 compiler has to recompile `std` for the target.
 
 ### Why does only libstd use `cfg(bootstrap)`?
 
+NOTE: for docs on `cfg(bootstrap)` itself, see [Complications of Bootstrapping][complications].
+
+[complications]: #complications-of-bootstrapping
+
 The `rustc` generated by the stage0 compiler is linked to the freshly-built
 `std`, which means that for the most part only `std` needs to be cfg-gated,
 so that `rustc` can use features added to std immediately after their addition,
@@ -258,7 +269,7 @@ Note this is different from any other Rust program: stage1 `rustc`
 is built by the _beta_ compiler, but using the _master_ version of libstd!
 
 The only time `rustc` uses `cfg(bootstrap)` is when it adds internal lints
-that use diagnostic items. This happens very rarely.
+that use diagnostic items, or when it uses unstable library features that were recently changed.
 
 ### What is a 'sysroot'?
 
diff --git a/src/doc/rustc-dev-guide/src/building/compiler-documenting.md b/src/doc/rustc-dev-guide/src/building/compiler-documenting.md
index 965e004c9..4e72bf994 100644
--- a/src/doc/rustc-dev-guide/src/building/compiler-documenting.md
+++ b/src/doc/rustc-dev-guide/src/building/compiler-documenting.md
@@ -31,6 +31,8 @@ like the standard library (std) or the compiler (rustc).
   ./x.py doc compiler library
   ```
 
+  See [the nightly docs index page](https://doc.rust-lang.org/nightly/) for a full list of books.
+
 - Document internal rustc items
 
   Compiler documentation is not built by default.
diff --git a/src/doc/rustc-dev-guide/src/building/how-to-build-and-run.md b/src/doc/rustc-dev-guide/src/building/how-to-build-and-run.md
index 6651b3691..59893bdc1 100644
--- a/src/doc/rustc-dev-guide/src/building/how-to-build-and-run.md
+++ b/src/doc/rustc-dev-guide/src/building/how-to-build-and-run.md
@@ -1,5 +1,7 @@
 # How to build and run the compiler
 
+<!-- toc -->
+
 The compiler is built using a tool called `x.py`. You will need to
 have Python installed to run it.
 
@@ -22,6 +24,29 @@ git clone https://github.com/rust-lang/rust.git
 cd rust
 ```
 
+### Shallow clone the repository
+
+Due to the size of the repository, cloning on a slower internet connection can take a long time.
+To sidestep this, you can use the `--depth N` option with the `git clone` command.
+This instructs `git` to perform a "shallow clone", cloning the repository but truncating it to
+the last `N` commits.
+
+Passing `--depth 1` tells `git` to clone the repository but truncate the history to the latest
+commit that is on the `master` branch, which is usually fine for browsing the source code or
+building the compiler.
+
+```bash
+git clone --depth 1 https://github.com/rust-lang/rust.git
+cd rust
+```
+
+> **NOTE**: A shallow clone limits which `git` commands can be run.
+> If you intend to work on and contribute to the compiler, it is
+> generally recommended to fully clone the repository [as shown above](#get-the-source-code).
+> 
+> For example, `git bisect` and `git blame` require access to the commit history,
+> so they don't work if the repository was cloned with `--depth 1`.
+
 ## What is `x.py`?
 
 `x.py` is the build tool for the `rust` repository. It can build docs, run tests, and compile the
@@ -45,14 +70,41 @@ You can install it with `cargo install --path src/tools/x`.
 To start, run `./x.py setup`. This will do some initialization and create a
 `config.toml` for you with reasonable defaults.
 
-Alternatively, you can write `config.toml` by hand. See `config.toml.example` for all the available
+Alternatively, you can write `config.toml` by hand. See `config.example.toml` for all the available
 settings and explanations of them. See `src/bootstrap/defaults` for common settings to change.
 
 If you have already built `rustc` and you change settings related to LLVM, then you may have to
 execute `rm -rf build` for subsequent configuration changes to take effect. Note that `./x.py
 clean` will not cause a rebuild of LLVM.
 
-## Building the compiler
+## Common `x.py` commands
+
+Here are the basic invocations of the `x.py` commands most commonly used when
+working on `rustc`, `std`, `rustdoc`, and other tools.
+
+| Command | When to use it |
+| --- | --- |
+| `./x.py check` | Quick check to see if most things compile; [rust-analyzer can run this automatically for you][rust-analyzer] |
+| `./x.py build` | Builds `rustc`, `std`, and `rustdoc` |
+| `./x.py test` | Runs all tests |
+| `./x.py fmt` | Formats all code |
+
+As written, these commands are reasonable starting points. However, there are
+additional options and arguments for each of them that are worth learning for
+serious development work. In particular, `./x.py build` and `./x.py test`
+provide many ways to compile or test a subset of the code, which can save a lot
+of time.
+
+Also, note that `x.py` supports all kinds of path suffixes for `compiler`, `library`,
+and `src/tools` directories. So, you can simply run `x.py test tidy` instead of
+`x.py test src/tools/tidy`. Or, `x.py build std` instead of `x.py build library/std`.
+
+[rust-analyzer]: ./building/suggested.html#configuring-rust-analyzer-for-rustc
+
+See the chapters on [building](./building/how-to-build-and-run.md),
+[testing](./tests/intro.md), and [rustdoc](./rustdoc.md) for more details.
+
+### Building the compiler
 
 Note that building will require a relatively large amount of storage space.
 You may want to have upwards of 10 or 15 gigabytes available to build the compiler.
@@ -98,7 +150,7 @@ build. The **full** `rustc` build (what you get with `./x.py build
 
 You almost never need to do this.
 
-## Build specific components
+### Build specific components
 
 If you are working on the standard library, you probably don't need to build
 the compiler unless you are planning to use a recently added nightly feature.
@@ -188,7 +240,7 @@ Note that building for some targets requires having external dependencies instal
 (e.g. building musl targets requires a local copy of musl).
 Any target-specific configuration (e.g. the path to a local copy of musl)
 will need to be provided by your `config.toml`.
-Please see `config.toml.example` for information on target-specific configuration keys.
+Please see `config.example.toml` for information on target-specific configuration keys.
 
 For examples of the complete configuration necessary to build a target, please visit
 [the rustc book](https://doc.rust-lang.org/rustc/platform-support.html),
diff --git a/src/doc/rustc-dev-guide/src/building/new-target.md b/src/doc/rustc-dev-guide/src/building/new-target.md
index f999a9472..629445be6 100644
--- a/src/doc/rustc-dev-guide/src/building/new-target.md
+++ b/src/doc/rustc-dev-guide/src/building/new-target.md
@@ -4,6 +4,8 @@ These are a set of steps to add support for a new target. There are
 numerous end states and paths to get there, so not all sections may be
 relevant to your desired goal.
 
+<!-- toc -->
+
 ## Specifying a new LLVM
 
 For very new targets, you may need to use a different fork of LLVM
diff --git a/src/doc/rustc-dev-guide/src/building/suggested.md b/src/doc/rustc-dev-guide/src/building/suggested.md
index 2e2592094..3049d87db 100644
--- a/src/doc/rustc-dev-guide/src/building/suggested.md
+++ b/src/doc/rustc-dev-guide/src/building/suggested.md
@@ -3,6 +3,8 @@
 The full bootstrapping process takes quite a while. Here are some suggestions
 to make your life easier.
 
+<!-- toc -->
+
 ## Installing a pre-push hook
 
 CI will automatically fail your build if it doesn't pass `tidy`, our
@@ -24,20 +26,20 @@ You can also install the hook as a step of running `./x.py setup`!
 `rust-analyzer` can help you check and format your code whenever you save
 a file. By default, `rust-analyzer` runs the `cargo check` and `rustfmt`
 commands, but you can override these commands to use more adapted versions
-of these tools when hacking on `rustc`. For example, `x.py setup` will prompt
+of these tools when hacking on `rustc`. For example, `x.py setup vscode` will prompt
 you to create a `.vscode/settings.json` file which will configure Visual Studio code.
 This will ask `rust-analyzer` to use `./x.py check` to check the sources, and the
 stage 0 rustfmt to format them.
-The recommended `rust-analyzer` settings live at [`src/etc/vscode_settings.json`].
+The recommended `rust-analyzer` settings live at [`src/etc/rust_analyzer_settings.json`].
 
 If you have enough free disk space and you would like to be able to run `x.py` commands while
 rust-analyzer runs in the background, you can also add `--build-dir build-rust-analyzer` to the
 `overrideCommand` to avoid x.py locking.
 
 If you're running `coc.nvim`, you can use `:CocLocalConfig` to create a
-`.vim/coc-settings.json` and copy the settings from [`src/etc/vscode_settings.json`].
+`.vim/coc-settings.json` and copy the settings from [`src/etc/rust_analyzer_settings.json`].
 
-[`src/etc/vscode_settings.json`]: https://github.com/rust-lang/rust/blob/master/src/etc/vscode_settings.json
+[`src/etc/rust_analyzer_settings.json`]: https://github.com/rust-lang/rust/blob/master/src/etc/rust_analyzer_settings.json
 
 If running `./x.py check` on save is inconvenient, in VS Code you can use a [Build
 Task] instead:
@@ -259,8 +261,8 @@ If you're using nix, you can use the following nix-shell to work on Rust:
 
 # This file contains a development shell for working on rustc.
 let
-  # Build configuration for rust-lang/rust. Based on `config.toml.example` from
-  # `1bd30ce2aac40c7698aa4a1b9520aa649ff2d1c5`.
+  # Build configuration for rust-lang/rust. Based on `config.example.toml` (then called
+  # `config.toml.example`) from `1bd30ce2aac40c7698aa4a1b9520aa649ff2d1c5`
   config = pkgs.writeText "rustc-config" ''
     profile = "compiler" # you may want to choose a different profile, like `library` or `tools`
     changelog-seen = 2
@@ -289,7 +291,7 @@ let
       # Files that are ignored by ripgrep when searching.
       ignoreFile = pkgs.writeText "rustc-rgignore" ''
         configure
-        config.toml.example
+        config.example.toml
         x.py
         LICENSE-MIT
         LICENSE-APACHE
diff --git a/src/doc/rustc-dev-guide/src/compiler-debugging.md b/src/doc/rustc-dev-guide/src/compiler-debugging.md
index 6052ea58a..65c3cadbb 100644
--- a/src/doc/rustc-dev-guide/src/compiler-debugging.md
+++ b/src/doc/rustc-dev-guide/src/compiler-debugging.md
@@ -42,7 +42,7 @@ otherwise you need to disable new symbol-mangling-version in `config.toml`.
 new-symbol-mangling = false
 ```
 
-> See the comments in `config.toml.example` for more info.
+> See the comments in `config.example.toml` for more info.
 
 You will need to rebuild the compiler after changing any configuration option.
 
@@ -269,7 +269,7 @@ on *why* it was changed.  See [this tutorial][bisect-tutorial] on how to use
 it.
 
 [bisect]: https://github.com/rust-lang/cargo-bisect-rustc
-[bisect-tutorial]: https://github.com/rust-lang/cargo-bisect-rustc/blob/master/TUTORIAL.md
+[bisect-tutorial]: https://rust-lang.github.io/cargo-bisect-rustc/tutorial.html
 
 ## Downloading Artifacts from Rust's CI
 
diff --git a/src/doc/rustc-dev-guide/src/const-eval/interpret.md b/src/doc/rustc-dev-guide/src/const-eval/interpret.md
index ee044505e..fbf781b96 100644
--- a/src/doc/rustc-dev-guide/src/const-eval/interpret.md
+++ b/src/doc/rustc-dev-guide/src/const-eval/interpret.md
@@ -82,7 +82,7 @@ The next statement asserts that said boolean is `0`. In case the assertion
 fails, its error message is used for reporting a compile-time error.
 
 Since it does not fail, `Operand::Immediate(Immediate::Scalar(Scalar::Raw {
-data: 4054, .. }))` is stored in the virtual memory was allocated before the
+data: 4054, .. }))` is stored in the virtual memory it was allocated before the
 evaluation. `_0` always refers to that location directly.
 
 After the evaluation is done, the return value is converted from [`Operand`] to
diff --git a/src/doc/rustc-dev-guide/src/contributing.md b/src/doc/rustc-dev-guide/src/contributing.md
index 383660fc1..d6037c7f1 100644
--- a/src/doc/rustc-dev-guide/src/contributing.md
+++ b/src/doc/rustc-dev-guide/src/contributing.md
@@ -1,32 +1,7 @@
-# Contributing to Rust
-
-Thank you for your interest in contributing to Rust! There are many ways to
-contribute, and we appreciate all of them.
+# Contribution Procedures
 
 <!-- toc -->
 
-If you have questions, please make a post on [internals.rust-lang.org][internals] or
-hop on the [Rust Discord server][rust-discord] or [Rust Zulip server][rust-zulip].
-
-As a reminder, all contributors are expected to follow our [Code of Conduct][coc].
-
-If this is your first time contributing, the [Getting Started] and
-[walkthrough] chapters can give you a good example of how a typical
-contribution would go.
-
-[internals]: https://internals.rust-lang.org
-[rust-discord]: http://discord.gg/rust-lang
-[rust-zulip]: https://rust-lang.zulipchat.com
-[coc]: https://www.rust-lang.org/conduct.html
-[walkthrough]: ./walkthrough.md
-[Getting Started]: ./getting-started.md
-
-## Feature Requests
-
-Feature requests need to go through a process to be approved by the relevant
-teams. Usually this requires a Final Comment Period (FCP) or even a Request for
-Comments (RFC). See [Getting Started] for more information about these processes.
-
 ## Bug Reports
 
 While bugs are unfortunate, they're a reality in software. We can't fix what we
@@ -58,6 +33,80 @@ Opening an issue is as easy as following [this
 link](https://github.com/rust-lang/rust/issues/new/choose) and filling out the fields
 in the appropriate provided template.
 
+## Bug Fixes or "Normal" code changes
+
+For most PRs, no special procedures are needed. You can just [open a PR][prs], and it
+will be reviewed, approved, and merged. This includes most bug fixes,
+refactorings, and other user-invisible changes. The next few sections talk
+about exceptions to this rule.
+
+Also, note that it is perfectly acceptable to open WIP PRs or GitHub [Draft
+PRs][draft]. Some people prefer to do this so they can get feedback along the
+way or share their code with a collaborator. Others do this so they can utilize
+the CI to build and test their PR (e.g. if you are developing on a laptop).
+
+[prs]: #pull-requests
+[draft]: https://github.blog/2019-02-14-introducing-draft-pull-requests/
+
+## New Features
+
+Rust has strong backwards-compatibility guarantees. Thus, new features can't
+just be implemented directly in stable Rust. Instead, we have 3 release
+channels: stable, beta, and nightly.
+
+- **Stable**: this is the latest stable release for general usage.
+- **Beta**: this is the next release (will be stable within 6 weeks).
+- **Nightly**: follows the `master` branch of the repo. This is the only
+  channel where unstable, incomplete, or experimental features are usable with
+  feature gates.
+
+See [this chapter on implementing new features](./implementing_new_features.md) for more
+information.
+
+### Breaking Changes
+
+Breaking changes have a [dedicated section][breaking-changes] in the dev-guide.
+
+[breaking-changes]: ./bug-fix-procedure.md
+
+### Major Changes
+
+The compiler team has a special process for large changes, whether or not they
+cause breakage. This process is called a Major Change Proposal (MCP). MCP is a
+relatively lightweight mechanism for getting feedback on large changes to the
+compiler (as opposed to a full RFC or a design meeting with the team).
+
+Example of things that might require MCPs include major refactorings, changes
+to important types, or important changes to how the compiler does something, or
+smaller user-facing changes.
+
+**When in doubt, ask on [zulip][z]. It would be a shame to put a lot of work
+into a PR that ends up not getting merged!** [See this document][mcpinfo] for
+more info on MCPs.
+
+[mcpinfo]: https://forge.rust-lang.org/compiler/mcp.html
+[z]: https://rust-lang.zulipchat.com/#narrow/stream/131828-t-compiler
+
+### Performance
+
+Compiler performance is important. We have put a lot of effort over the last
+few years into [gradually improving it][perfdash].
+
+[perfdash]: https://perf.rust-lang.org/dashboard.html
+
+If you suspect that your change may cause a performance regression (or
+improvement), you can request a "perf run" (your reviewer may also request one
+before approving). This is yet another bot that will compile a collection of
+benchmarks on a compiler with your changes. The numbers are reported
+[here][perf], and you can see a comparison of your changes against the latest
+master.
+
+For an introduction to the performance of Rust code in general
+which would also be useful in rustc development, see [The Rust Performance Book].
+
+[perf]: https://perf.rust-lang.org
+[The Rust Performance Book]: https://nnethercote.github.io/perf-book/
+
 ## Pull Requests
 
 Pull requests (or PRs for short) are the primary mechanism we use to change Rust.
@@ -96,6 +145,42 @@ For a full list of possible `groupname` check the `adhoc_groups` section at the
 or the list of teams in the [rust-lang teams
 database](https://github.com/rust-lang/team/tree/master/teams).
 
+### Waiting for reviews
+
+> NOTE
+>
+> Pull request reviewers are often working at capacity,
+> and many of them are contributing on a volunteer basis.
+> In order to minimize review delays,
+> pull request authors and assigned reviewers should ensure that the review label
+> (`S-waiting-on-review` and `S-waiting-on-author`) stays updated,
+> invoking these commands when appropriate:
+>
+> - `@rustbot author`:
+>   the review is finished,
+>   and PR author should check the comments and take action accordingly.
+>
+> - `@rustbot review`:
+>   the author is ready for a review,
+>   and this PR will be queued again in the reviewer's queue.
+
+Please note that the reviewers are humans, who for the most part work on `rustc`
+in their free time. This means that they can take some time to respond and review
+your PR. It also means that reviewers can miss some PRs that are assigned to them.
+
+To try to move PRs forward, the Triage WG regularly goes through all PRs that
+are waiting for review and haven't been discussed for at least 2 weeks. If you
+don't get a review within 2 weeks, feel free to ask the Triage WG on
+Zulip ([#t-release/triage]). They have knowledge of when to ping, who might be
+on vacation, etc.
+
+The reviewer may request some changes using the GitHub code review interface.
+They may also request special procedures (such as a [crater] run; [see
+below][break]) for some PRs.
+
+[r?]: https://github.com/rust-lang/rust/pull/78133#issuecomment-712692371
+[#t-release/triage]: https://rust-lang.zulipchat.com/#narrow/stream/242269-t-release.2Ftriage
+[break]: #breaking-changes
 ### CI
 
 In addition to being reviewed by a human, pull requests are automatically tested
@@ -104,6 +189,8 @@ a pull request, CI builds the compiler and tests it against the
 [compiler test suite][rctd], and also performs other tests such as checking that
 your pull request is in compliance with Rust's style guidelines.
 
+[rctd]: tests/intro.md
+
 Running continuous integration tests allows PR authors to catch mistakes early
 without going through a first review cycle, and also helps reviewers stay aware
 of the status of a particular pull request.
@@ -135,6 +222,8 @@ Changes that are rolled up are tested and merged alongside other PRs, to
 speed the process up. Typically only small changes that are expected not to conflict
 with one another are marked as "always roll up".
 
+Be patient; this can take a while and the queue can sometimes be long. PRs are never merged by hand.
+
 [@rustbot]: https://github.com/rustbot
 [@bors]: https://github.com/bors
 [merge-queue]: https://bors.rust-lang.org/queue/rust
@@ -179,161 +268,19 @@ the issue in question.
 [labeling]: ./rustbot.md#issue-relabeling
 [closing-keywords]: https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue
 
-### External Dependencies (subtree)
-
-As a developer to this repository, you don't have to treat the following external projects
-differently from other crates that are directly in this repo:
-
-* [Clippy](https://github.com/rust-lang/rust-clippy)
-* [Miri]
-* [rustfmt](https://github.com/rust-lang/rustfmt)
-* [rust-analyzer](https://github.com/rust-lang/rust-analyzer)
-
-In contrast to `submodule` dependencies
-(see below for those), the `subtree` dependencies are just regular files and directories which can
-be updated in tree. However, if possible, enhancements, bug fixes, etc. specific
-to these tools should be filed against the tools directly in their respective
-upstream repositories. The exception is that when rustc changes are required to
-implement a new tool feature or test, that should happen in one collective rustc PR.
-
-#### Synchronizing a subtree
-
-Periodically the changes made to subtree based dependencies need to be synchronized between this
-repository and the upstream tool repositories.
-
-Subtree synchronizations are typically handled by the respective tool maintainers. Other users
-are welcome to submit synchronization PRs, however, in order to do so you will need to modify
-your local git installation and follow a very precise set of instructions.
-These instructions are documented, along with several useful tips and tricks, in the
-[syncing subtree changes][clippy-sync-docs] section in Clippy's Contributing guide.
-The instructions are applicable for use with any subtree based tool, just be sure to
-use the correct corresponding subtree directory and remote repository.
-
-The synchronization process goes in two directions: `subtree push` and `subtree pull`.
-
-A `subtree push` takes all the changes that happened to the copy in this repo and creates commits
-on the remote repo that match the local changes. Every local
-commit that touched the subtree causes a commit on the remote repo, but
-is modified to move the files from the specified directory to the tool repo root.
-
-A `subtree pull` takes all changes since the last `subtree pull`
-from the tool repo and adds these commits to the rustc repo along with a merge commit that moves
-the tool changes into the specified directory in the Rust repository.
-
-It is recommended that you always do a push first and get that merged to the tool master branch.
-Then, when you do a pull, the merge works without conflicts.
-While it's definitely possible to resolve conflicts during a pull, you may have to redo the conflict
-resolution if your PR doesn't get merged fast enough and there are new conflicts. Do not try to
-rebase the result of a `git subtree pull`, rebasing merge commits is a bad idea in general.
-
-You always need to specify the `-P` prefix to the subtree directory and the corresponding remote
-repository. If you specify the wrong directory or repository
-you'll get very fun merges that try to push the wrong directory to the wrong remote repository.
-Luckily you can just abort this without any consequences by throwing away either the pulled commits
-in rustc or the pushed branch on the remote and try again. It is usually fairly obvious
-that this is happening because you suddenly get thousands of commits that want to be synchronized.
-
-[clippy-sync-docs]: https://doc.rust-lang.org/nightly/clippy/development/infrastructure/sync.html
-
-#### Creating a new subtree dependency
-
-If you want to create a new subtree dependency from an existing repository, call (from this
-repository's root directory!)
-
-```
-git subtree add -P src/tools/clippy https://github.com/rust-lang/rust-clippy.git master
-```
-
-This will create a new commit, which you may not rebase under any circumstances! Delete the commit
-and redo the operation if you need to rebase.
-
-Now you're done, the `src/tools/clippy` directory behaves as if Clippy were
-part of the rustc monorepo, so no one but you (or others that synchronize
-subtrees) actually needs to use `git subtree`.
-
-
-### External Dependencies (submodules)
-
-Building Rust will also use external git repositories tracked using [git
-submodules]. The complete list may be found in the [`.gitmodules`] file. Some
-of these projects are required (like `stdarch` for the standard library) and
-some of them are optional (like [Miri]).
-
-Usage of submodules is discussed more in the [Using Git
-chapter](git.md#git-submodules).
-
-Some of the submodules are allowed to be in a "broken" state where they
-either don't build or their tests don't pass, e.g. the documentation books
-like [The Rust Reference]. Maintainers of these projects will be notified
-when the project is in a broken state, and they should fix them as soon
-as possible. The current status is tracked on the [toolstate website].
-More information may be found on the Forge [Toolstate chapter].
-
-Breakage is not allowed in the beta and stable channels, and must be addressed
-before the PR is merged. They are also not allowed to be broken on master in
-the week leading up to the beta cut.
-
-[git submodules]: https://git-scm.com/book/en/v2/Git-Tools-Submodules
-[`.gitmodules`]: https://github.com/rust-lang/rust/blob/master/.gitmodules
-[The Rust Reference]: https://github.com/rust-lang/reference/
-[toolstate website]: https://rust-lang-nursery.github.io/rust-toolstate/
-[Toolstate chapter]: https://forge.rust-lang.org/infra/toolstate.html
-
-#### Breaking Tools Built With The Compiler
-
-Rust's build system builds a number of tools that make use of the internals of
-the compiler and that are hosted in a separate repository, and included in Rust
-via git submodules (such as [Miri]). If these tools break because of your
-changes, you may run into a sort of "chicken and egg" problem. These tools rely
-on the latest compiler to be built so you can't update them (in their own
-repositories) to reflect your changes to the compiler until those changes are
-merged into the compiler. At the same time, you can't get your changes merged
-into the compiler because the rust-lang/rust build won't pass until those tools
-build and pass their tests.
-
-Luckily, a feature was
-[added to Rust's build](https://github.com/rust-lang/rust/issues/45861) to make
-all of this easy to handle. The idea is that we allow these tools to be
-"broken", so that the rust-lang/rust build passes without trying to build them,
-then land the change in the compiler, and go update the tools that you
-broke. Some tools will require waiting for a nightly release before this can
-happen, while others use the builds uploaded after each bors merge and thus can
-be updated immediately (check the tool's documentation for details). Once you're
-done and the tools are working again, you go back in the compiler and update the
-tools so they can be distributed again.
-
-This should avoid a bunch of synchronization dances and is also much easier on contributors as
-there's no need to block on tools changes going upstream.
-
-Here are those same steps in detail:
-
-1. (optional) First, if it doesn't exist already, create a `config.toml` by copying
-   `config.toml.example` in the root directory of the Rust repository.
-   Set `submodules = false` in the `[build]` section. This will prevent `x.py`
-   from resetting to the original branch after you make your changes. If you
-   need to [update any submodules to their latest versions](#updating-submodules),
-   see the section of this file about that for more information.
-2. (optional) Run `./x.py test src/tools/cargo` (substituting the submodule
-   that broke for `cargo`). Fix any errors in the submodule (and possibly others).
-3. (optional) Make commits for your changes and send them to upstream repositories as a PR.
-4. (optional) Maintainers of these submodules will **not** merge the PR. The PR can't be
-   merged because CI will be broken. You'll want to write a message on the PR referencing
-   your change, and how the PR should be merged once your change makes it into a nightly.
-5. Wait for your PR to merge.
-6. Wait for a nightly.
-7. (optional) Help land your PR on the upstream repository now that your changes are in nightly.
-8. (optional) Send a PR to rust-lang/rust updating the submodule.
+## External Dependencies
 
+This section has moved to ["Using External Repositories"](./external-repos.md).
 
 ## Writing Documentation
 
 Documentation improvements are very welcome. The source of `doc.rust-lang.org`
 is located in [`src/doc`] in the tree, and standard API documentation is generated
-from the source code itself (e.g. [`lib.rs`]). Documentation pull requests function
-in the same way as other pull requests.
+from the source code itself (e.g. [`library/std/src/lib.rs`][std-root]). Documentation pull requests
+function in the same way as other pull requests.
 
 [`src/doc`]: https://github.com/rust-lang/rust/tree/master/src/doc
-[`lib.rs`]: https://github.com/rust-lang/rust/blob/master/library/std/src/lib.rs#L1
+[std-root]: https://github.com/rust-lang/rust/blob/master/library/std/src/lib.rs#L1
 
 To find documentation-related issues, sort by the [A-docs label][adocs].
 
@@ -343,14 +290,11 @@ You can find documentation style guidelines in [RFC 1574][rfc1574].
 
 [rfc1574]: https://github.com/rust-lang/rfcs/blob/master/text/1574-more-api-documentation-conventions.md#appendix-a-full-conventions-text
 
-In many cases, you don't need a full `./x.py doc --stage 2`, which will build
-the entire stage 2 compiler and compile the various books published on
-[doc.rust-lang.org][docs]. When updating documentation for the standard library,
-first try `./x.py doc library`. If that fails, or if you need to
-see the output from the latest version of `rustdoc`, add `--stage 1`.
-Results should appear in `build/host/doc`.
-
-[docs]: https://doc.rust-lang.org
+To build the standard library documentation, use `x doc --stage 0 library --open`.
+To build the documentation for a book (e.g. the unstable book), use `x doc src/doc/unstable-book.`
+Results should appear in `build/host/doc`, as well as automatically open in your default browser.
+See [Building Documentation](./building/compiler-documenting.md#building-documentation) for more
+information.
 
 You can also use `rustdoc` directly to check small fixes. For example,
 `rustdoc src/doc/reference.md` will render reference to `doc/reference.html`.
@@ -366,7 +310,7 @@ There are issues for beginners and advanced compiler devs alike!
 Just a few things to keep in mind:
 
 - Please limit line length to 100 characters. This is enforced by CI, and you can run the checks
-  locally with `ci/check_line_lengths.sh`.
+  locally with `ci/lengthcheck.sh`.
 
 - When contributing text to the guide, please contextualize the information with some time period
   and/or a reason so that the reader knows how much to trust or mistrust the information.
@@ -431,122 +375,99 @@ updated sort][lru] is good for finding issues like this.
 [Thanks to `@rustbot`][rustbot], anyone can help triage issues by adding
 appropriate labels to issues that haven't been triaged yet:
 
-* Yellow, **A**-prefixed labels state which **area** of the project an issue
-  relates to.
-
-* Magenta, **B**-prefixed labels identify bugs which are **blockers**.
-
-* Dark blue, **beta-** labels track changes which need to be backported into
-  the beta branches.
-
-* Light purple, **C**-prefixed labels represent the **category** of an issue.
-
-* Green, **E**-prefixed labels explain the level of **experience** necessary
-  to fix the issue.
-
-* The dark blue **final-comment-period** label marks bugs that are using the
-  RFC signoff functionality of [rfcbot] and are currently in the final
-  comment period.
-
-* Red, **I**-prefixed labels indicate the **importance** of the issue. The
-  [I-nominated][inom] label indicates that an issue has been nominated for
-  discussion at the next meeting of the team tagged using a
-  **T**-prefixed label. Similarly, the [I-prioritize][ipri] indicates
-  that an issue has been requested to be prioritized by the appropriate
-  team.
-
-* The purple **metabug** label marks lists of bugs collected by other
-  categories.
-
-* Purple gray, **O**-prefixed labels are the **operating system** or platform
-  that this issue is specific to.
-
-* Orange, **P**-prefixed labels indicate a bug's **priority**. These labels
-  can be assigned by anyone that understand the issue and is able to
-  prioritize it, and replace the [I-prioritize][ipri] label.
-
-* The gray **proposed-final-comment-period** label marks bugs that are using
-  the RFC signoff functionality of [rfcbot] and are currently awaiting
-  signoff of all team members in order to enter the final comment period.
-
-* Pink, **regression**-prefixed labels track regressions from stable to the
-  release channels.
-
-* The light orange **relnotes** label marks issues that should be documented in
-  the release notes of the next release.
-
-* Gray, **S**-prefixed labels are used for tracking the **status** of pull
-  requests.
-
-* Blue, **T**-prefixed bugs denote which **team** the issue belongs to.
-
-If you're looking for somewhere to start, check out the [E-easy][eeasy] tag.
-
-[rustbot]: ./rustbot.md
-[inom]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AI-nominated
-[ipri]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AI-prioritize
-[eeasy]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AE-easy
 [lru]: https://github.com/rust-lang/rust/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-asc
-[rfcbot]: https://github.com/anp/rfcbot-rs/
-
-## Out-of-tree Contributions
-
-There are a number of other ways to contribute to Rust that don't deal with
-rust-lang/rust:
-
-* Answer questions in the _Get Help!_ channels on the [Rust Discord
-  server][rust-discord], on [users.rust-lang.org][users], or on
-  [StackOverflow][so].
-* Participate in the [RFC process](https://github.com/rust-lang/rfcs).
-* Find a [requested community library][community-library], build it, and publish
-  it to [Crates.io](http://crates.io). Easier said than done, but very, very
-  valuable!
+[rustbot]: ./rustbot.md
 
-[rust-discord]: https://discord.gg/rust-lang
-[users]: https://users.rust-lang.org/
-[so]: http://stackoverflow.com/questions/tagged/rust
-[community-library]: https://github.com/rust-lang/rfcs/labels/A-community-library
+<style>
+.label-color {
+    border-radius:0.5em;
+}
+table td:nth-child(2) {
+    white-space: nowrap;
+}
+
+</style>
+
+| Labels | Color | Description |
+|--------|-------|-------------|
+| [A-]   | <span class="label-color" style="background-color:#f7e101;">&#x2003;</span>&nbsp;Yellow | The **area** of the project an issue relates to. |
+| [B-]   | <span class="label-color" style="background-color:#d304cb;">&#x2003;</span>&nbsp;Magenta | Issues which are **blockers**. |
+| [beta-] | <span class="label-color" style="background-color:#1e76d9;">&#x2003;</span>&nbsp;Dark Blue | Tracks changes which need to be [backported to beta][beta-backport] |
+| [C-] | <span class="label-color" style="background-color:#f5f1fd;">&#x2003;</span>&nbsp;Light Purple | The **category** of an issue. |
+| [D-] | <span class="label-color" style="background-color:#c9f7a3;">&#x2003;</span>&nbsp;Mossy Green | Issues for **diagnostics**. |
+| [E-] | <span class="label-color" style="background-color:#02e10c;">&#x2003;</span>&nbsp;Green | The **experience** level necessary to fix an issue. |
+| [F-] | <span class="label-color" style="background-color:#f9c0cc;">&#x2003;</span>&nbsp;Peach | Issues for **nightly features**. |
+| [I-] | <span class="label-color" style="background-color:#e10c02;">&#x2003;</span>&nbsp;Red | The **importance** of the issue. |
+| [I-\*-nominated] | <span class="label-color" style="background-color:#e10c02;">&#x2003;</span>&nbsp;Red | The issue has been nominated for discussion at the next meeting of the corresponding team. |
+| [I-prioritize] | <span class="label-color" style="background-color:#e10c02;">&#x2003;</span>&nbsp;Red | The issue has been nominated for prioritization by the team tagged with a **T**-prefixed label. |
+| [metabug] | <span class="label-color" style="background-color:#5319e7;">&#x2003;</span>&nbsp;Purple | Bugs that collect other bugs. |
+| [O-] | <span class="label-color" style="background-color:#6e6ec0;">&#x2003;</span>&nbsp;Purple Grey | The **operating system** or platform that the issue is specific to. |
+| [P-] | <span class="label-color" style="background-color:#eb6420;">&#x2003;</span>&nbsp;Orange | The issue **priority**.  These labels can be assigned by anyone that understand the issue and is able to  prioritize it, and remove the [I-prioritize] label. |
+| [regression-] | <span class="label-color" style="background-color:#e4008a;">&#x2003;</span>&nbsp;Pink | Tracks regressions from a stable release. |
+| [relnotes] | <span class="label-color" style="background-color:#fad8c7;">&#x2003;</span>&nbsp;Light Orange | Changes that should be documented in the release notes of the next release. |
+| [S-] | <span class="label-color" style="background-color:#d3dddd;">&#x2003;</span>&nbsp;Gray | Tracks the **status** of pull requests. |
+| [S-tracking-] | <span class="label-color" style="background-color:#4682b4;">&#x2003;</span>&nbsp;Steel Blue | Tracks the **status** of [tracking issues]. |
+| [stable-] | <span class="label-color" style="background-color:#00229c;">&#x2003;</span>&nbsp;Dark Blue | Tracks changes which need to be [backported to stable][stable-backport] in anticipation of a point release. |
+| [T-] | <span class="label-color" style="background-color:#bfd4f2;">&#x2003;</span>&nbsp;Blue | Denotes which **team** the issue belongs to. |
+| [WG-] | <span class="label-color" style="background-color:#c2e0c6;">&#x2003;</span>&nbsp;Green | Denotes which **working group** the issue belongs to. |
+
+
+[A-]: https://github.com/rust-lang/rust/labels?q=A
+[B-]: https://github.com/rust-lang/rust/labels?q=B
+[C-]: https://github.com/rust-lang/rust/labels?q=C
+[D-]: https://github.com/rust-lang/rust/labels?q=D
+[E-]: https://github.com/rust-lang/rust/labels?q=E
+[F-]: https://github.com/rust-lang/rust/labels?q=F
+[I-]: https://github.com/rust-lang/rust/labels?q=I
+[O-]: https://github.com/rust-lang/rust/labels?q=O
+[P-]: https://github.com/rust-lang/rust/labels?q=P
+[S-]: https://github.com/rust-lang/rust/labels?q=S
+[T-]: https://github.com/rust-lang/rust/labels?q=T
+[WG-]: https://github.com/rust-lang/rust/labels?q=WG
+[stable-]: https://github.com/rust-lang/rust/labels?q=stable
+[beta-]: https://github.com/rust-lang/rust/labels?q=beta
+[I-\*-nominated]: https://github.com/rust-lang/rust/labels?q=nominated
+[I-prioritize]: https://github.com/rust-lang/rust/labels/I-prioritize
+[tracking issues]: https://github.com/rust-lang/rust/labels/C-tracking-issue
+[beta-backport]: https://forge.rust-lang.org/release/backporting.html#beta-backporting-in-rust-langrust
+[stable-backport]: https://forge.rust-lang.org/release/backporting.html#stable-backporting-in-rust-langrust
+[metabug]: https://github.com/rust-lang/rust/labels/metabug
+[regression-]: https://github.com/rust-lang/rust/labels?q=regression
+[relnotes]: https://github.com/rust-lang/rust/labels/relnotes
+[S-tracking-]: https://github.com/rust-lang/rust/labels?q=s-tracking
+
+### Rfcbot labels
+
+[rfcbot] uses its own labels for tracking the process of coordinating
+asynchronous decisions, such as approving or rejecting a change.
+This is used for [RFCs], issues, and pull requests.
+
+| Labels | Color | Description |
+|--------|-------|-------------|
+| [proposed-final-comment-period] | <span class="label-color" style="background-color:#ededed;">&#x2003;</span>&nbsp;Gray | Currently awaiting signoff of all team members in order to enter the final comment period. |
+| [disposition-merge] | <span class="label-color" style="background-color:#008800;">&#x2003;</span>&nbsp;Green | Indicates the intent is to merge the change. |
+| [disposition-close] | <span class="label-color" style="background-color:#dd0000;">&#x2003;</span>&nbsp;Red | Indicates the intent is to not accept the change and close it. |
+| [disposition-postpone] | <span class="label-color" style="background-color:#ededed;">&#x2003;</span>&nbsp;Gray | Indicates the intent is to not accept the change at this time and postpone it to a later date. |
+| [final-comment-period] | <span class="label-color" style="background-color:#1e76d9;">&#x2003;</span>&nbsp;Blue | Currently soliciting final comments before merging or closing. |
+| [finished-final-comment-period] | <span class="label-color" style="background-color:#f9e189;">&#x2003;</span>&nbsp;Light Yellow | The final comment period has concluded, and the issue will be merged or closed. |
+| [postponed] | <span class="label-color" style="background-color:#fbca04;">&#x2003;</span>&nbsp;Yellow | The issue has been postponed. |
+| [closed] | <span class="label-color" style="background-color:#dd0000;">&#x2003;</span>&nbsp;Red | The issue has been rejected. |
+| [to-announce] | <span class="label-color" style="background-color:#ededed;">&#x2003;</span>&nbsp;Gray | Issues that have finished their final-comment-period and should be publicly announced. Note: the rust-lang/rust repository uses this label differently, to announce issues at the triage meetings. |
+
+[disposition-merge]: https://github.com/rust-lang/rust/labels/disposition-merge
+[disposition-close]: https://github.com/rust-lang/rust/labels/disposition-close
+[disposition-postpone]: https://github.com/rust-lang/rust/labels/disposition-postpone
+[proposed-final-comment-period]: https://github.com/rust-lang/rust/labels/proposed-final-comment-period
+[final-comment-period]: https://github.com/rust-lang/rust/labels/final-comment-period
+[finished-final-comment-period]: https://github.com/rust-lang/rust/labels/finished-final-comment-period
+[postponed]: https://github.com/rust-lang/rfcs/labels/postponed
+[closed]: https://github.com/rust-lang/rfcs/labels/closed
+[to-announce]: https://github.com/rust-lang/rfcs/labels/to-announce
+[rfcbot]: https://github.com/anp/rfcbot-rs/
+[RFCs]: https://github.com/rust-lang/rfcs
 
 ## Helpful Links and Information
 
-For people new to Rust, and just starting to contribute, or even for
-more seasoned developers, some useful places to look for information
-are:
-
-* This guide contains information about how various parts of the
-  compiler work and how to contribute to the compiler
-* [Rust Forge][rustforge] contains additional documentation, including
-  write-ups of how to achieve common tasks
-* The [Rust Internals forum][rif], a place to ask questions and
-  discuss Rust's internals
-* The [generated documentation for Rust's compiler][gdfrustc]
-* The [Rust reference][rr], even though it doesn't specifically talk about
-  Rust's internals, is a great resource nonetheless
-* Although out of date, [Tom Lee's great blog article][tlgba] is very helpful
-* [rustaceans.org][ro] is helpful, but mostly dedicated to IRC
-* The [Rust Compiler Testing Docs][rctd]
-* For [@bors], [this cheat sheet][cheatsheet] is helpful
-* Google is always helpful when programming.
-  You can [search all Rust documentation][gsearchdocs] (the standard library,
-  the compiler, the books, the references, and the guides) to quickly find
-  information about the language and compiler.
-* You can also use Rustdoc's built-in search feature to find documentation on
-  types and functions within the crates you're looking at. You can also search
-  by type signature! For example, searching for `* -> vec` should find all
-  functions that return a `Vec<T>`.
-  _Hint:_ Find more tips and keyboard shortcuts by typing `?` on any Rustdoc
-  page!
-* Don't be afraid to ask! The Rust community is friendly and helpful.
-
-[rustc dev guide]: about-this-guide.md
-[gdfrustc]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/
-[gsearchdocs]: https://www.google.com/search?q=site:doc.rust-lang.org+your+query+here
-[stddocs]: https://doc.rust-lang.org/std
-[rif]: http://internals.rust-lang.org
-[rr]: https://doc.rust-lang.org/book/README.html
-[rustforge]: https://forge.rust-lang.org/
-[tlgba]: https://tomlee.co/2014/04/a-more-detailed-tour-of-the-rust-compiler/
-[ro]: https://www.rustaceans.org/
-[rctd]: tests/intro.md
-[cheatsheet]: https://bors.rust-lang.org/
-[Miri]: https://github.com/rust-lang/miri
+This section has moved to the ["About this guide"][more-links] chapter.
+
+[more-links]: ./about-this-guide.md#other-places-to-find-information
diff --git a/src/doc/rustc-dev-guide/src/conventions.md b/src/doc/rustc-dev-guide/src/conventions.md
index 4dd0a2da9..521aeb4a5 100644
--- a/src/doc/rustc-dev-guide/src/conventions.md
+++ b/src/doc/rustc-dev-guide/src/conventions.md
@@ -29,7 +29,10 @@ pass the <!-- date-check: nov 2022 --> `--edition=2021` argument yourself when c
 
 <a name="copyright"></a>
 
+<!-- REUSE-IgnoreStart -->
+<!-- Prevent REUSE from interpreting the heading as a copyright notice -->
 ### Copyright notice
+<!-- REUSE-IgnoreEnd -->
 
 In the past, files began with a copyright and license notice. Please **omit**
 this notice for new files licensed under the standard terms (dual
diff --git a/src/doc/rustc-dev-guide/src/diagnostics.md b/src/doc/rustc-dev-guide/src/diagnostics.md
index d32de068e..daaffba7b 100644
--- a/src/doc/rustc-dev-guide/src/diagnostics.md
+++ b/src/doc/rustc-dev-guide/src/diagnostics.md
@@ -69,17 +69,12 @@ surrounded with backticks:
 error: the identifier `foo.bar` is invalid
 ```
 
-### Error explanations
+### Error codes and explanations
 
-Some errors include long form descriptions. They may be viewed with the
-`--explain` flag, or via the [error index]. Each explanation comes with an
-example of how to trigger it and advice on how to fix it.
-
-Please read [RFC 1567] for details on how to format and write long error
-codes.
-
-The descriptions are written in Markdown, and all of them are linked in the
-[`rustc_error_codes`] crate.
+Most errors have an associated error code. Error codes are linked to long-form
+explanations which contains an example of how to trigger the error and in-depth
+details about the error. They may be viewed with the `--explain` flag, or via
+the [error index].
 
 As a general rule, give an error a code (with an associated explanation) if the
 explanation would give more information than the error itself. A lot of the time
@@ -89,12 +84,15 @@ triggers to include useful information for all cases in the error, in which case
 it's a good idea to add an explanation.[^estebank]
 As always, if you are not sure, just ask your reviewer!
 
+If you decide to add a new error with an associated error code, please read
+[this section][error-codes] for a guide and important details about the
+process.
+
 [^estebank]: This rule of thumb was suggested by **@estebank** [here][estebank-comment].
 
-[`rustc_error_codes`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_error_codes/error_codes/index.html
 [error index]: https://doc.rust-lang.org/error-index.html
-[RFC 1567]: https://github.com/rust-lang/rfcs/blob/master/text/1567-long-error-codes-explanation-normalization.md
 [estebank-comment]: https://github.com/rust-lang/rustc-dev-guide/pull/967#issuecomment-733218283
+[error-codes]: ./diagnostics/error-codes.md
 
 ### Lints versus fixed diagnostics
 
diff --git a/src/doc/rustc-dev-guide/src/diagnostics/diagnostic-codes.md b/src/doc/rustc-dev-guide/src/diagnostics/diagnostic-codes.md
deleted file mode 100644
index 3618b43cd..000000000
--- a/src/doc/rustc-dev-guide/src/diagnostics/diagnostic-codes.md
+++ /dev/null
@@ -1,79 +0,0 @@
-# Diagnostic codes
-We generally try to assign each error message a unique code like `E0123`. These
-codes are defined in the compiler in the `diagnostics.rs` files found in each
-crate, which basically consist of macros. The codes come in two varieties: those
-that have an extended write-up, and those that do not. Whenever possible, if you
-are making a new code, you should write an extended write-up.
-
-### Allocating a fresh code
-
-Error codes are stored in `compiler/rustc_error_codes`.
-
-To create a new error, you first need to find the next available
-code. You can find it with `tidy`:
-
-```
-./x.py test tidy
-```
-
-This will invoke the tidy script, which generally checks that your code obeys
-our coding conventions. One of those jobs is to check that diagnostic codes are
-indeed unique. Once it is finished with that, tidy will print out the lowest
-unused code:
-
-```
-...
-tidy check (x86_64-apple-darwin)
-* 470 error codes
-* highest error code: E0591
-...
-```
-
-Here we see the highest error code in use is `E0591`, so we _probably_ want
-`E0592`. To be sure, run `rg E0592` and check, you should see no references.
-
-Ideally, you will write an extended description for your error,
-which will go in `rustc_error_codes/src/error_codes/E0592.md`.
-To register the error, open `rustc_error_codes/src/error_codes.rs` and add the
-code (in its proper numerical order) into` register_diagnostics!` macro, like
-this:
-
-```rust
-register_diagnostics! {
-    ...
-    E0592: include_str!("./error_codes/E0592.md"),
-}
-```
-
-But you can also add it without an extended description:
-
-```rust
-register_diagnostics! {
-    ...
-    E0592, // put a description here
-}
-```
-
-To actually issue the error, you can use the `struct_span_err!` macro:
-
-```rust
-struct_span_err!(self.tcx.sess, // some path to the session here
-                 span, // whatever span in the source you want
-                 E0592, // your new error code
-                 fluent::example::an_error_message)
-    .emit() // actually issue the error
-```
-
-If you want to add notes or other snippets, you can invoke methods before you
-call `.emit()`:
-
-```rust
-struct_span_err!(...)
-    .span_label(another_span, fluent::example::example_label)
-    .span_note(another_span, fluent::example::separate_note)
-    .emit_()
-```
-
-For an example of a PR adding an error code, see [#76143].
-
-[#76143]: https://github.com/rust-lang/rust/pull/76143
diff --git a/src/doc/rustc-dev-guide/src/diagnostics/error-codes.md b/src/doc/rustc-dev-guide/src/diagnostics/error-codes.md
new file mode 100644
index 000000000..2dbdb53fe
--- /dev/null
+++ b/src/doc/rustc-dev-guide/src/diagnostics/error-codes.md
@@ -0,0 +1,95 @@
+# Error codes
+We generally try to assign each error message a unique code like `E0123`. These
+codes are defined in the compiler in the `diagnostics.rs` files found in each
+crate, which basically consist of macros. All error codes have an associated
+explanation: new error codes must include them. Note that not all _historical_
+(no longer emitted) error codes have explanations.
+
+## Error explanations
+
+The explanations are written in Markdown (see the [CommonMark Spec] for
+specifics around syntax), and all of them are linked in the [`rustc_error_codes`]
+crate. Please read [RFC 1567] for details on how to format and write long error
+codes. As of <!-- date-check --> February 2023, there is an
+effort[^new-explanations] to replace this largely outdated RFC with a new more
+flexible standard.
+
+Error explanations should expand on the error message and provide details about
+_why_ the error occurs. It is not helpful for users to copy-paste a quick fix;
+explanations should help users understand why their code cannot be accepted by
+the compiler. Rust prides itself on helpful error messages and long-form
+explanations are no exception. However, before error explanations are
+overhauled[^new-explanations] it is a bit open as to how exactly they should be
+written, as always: ask your reviewer or ask around on the Rust Discord or Zulip.
+
+[^new-explanations]: See the draft RFC [here][new-explanations-rfc].
+
+[`rustc_error_codes`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_error_codes/error_codes/index.html
+[CommonMark Spec]: https://spec.commonmark.org/current/
+[RFC 1567]: https://github.com/rust-lang/rfcs/blob/master/text/1567-long-error-codes-explanation-normalization.md
+[new-explanations-rfc]: https://github.com/rust-lang/rfcs/pull/3370
+
+## Allocating a fresh code
+
+Error codes are stored in `compiler/rustc_error_codes`.
+
+To create a new error, you first need to find the next available
+code. You can find it with `tidy`:
+
+```
+./x.py test tidy
+```
+
+This will invoke the tidy script, which generally checks that your code obeys
+our coding conventions. Some of these jobs check error codes and ensure that
+there aren't duplicates, etc (the tidy check is defined in
+`src/tools/tidy/src/error_codes.rs`). Once it is finished with that, tidy will
+print out the highest used error code:
+
+```
+...
+tidy check
+Found 505 error codes
+Highest error code: `E0591`
+...
+```
+
+Here we see the highest error code in use is `E0591`, so we _probably_ want
+`E0592`. To be sure, run `rg E0592` and check, you should see no references.
+
+You will have to write an extended description for your error,
+which will go in `rustc_error_codes/src/error_codes/E0592.md`.
+To register the error, open `rustc_error_codes/src/error_codes.rs` and add the
+code (in its proper numerical order) into` register_diagnostics!` macro, like
+this:
+
+```rust
+register_diagnostics! {
+    ...
+    E0592: include_str!("./error_codes/E0592.md"),
+}
+```
+
+To actually issue the error, you can use the `struct_span_err!` macro:
+
+```rust
+struct_span_err!(self.tcx.sess, // some path to the session here
+                 span, // whatever span in the source you want
+                 E0592, // your new error code
+                 fluent::example::an_error_message)
+    .emit() // actually issue the error
+```
+
+If you want to add notes or other snippets, you can invoke methods before you
+call `.emit()`:
+
+```rust
+struct_span_err!(...)
+    .span_label(another_span, fluent::example::example_label)
+    .span_note(another_span, fluent::example::separate_note)
+    .emit()
+```
+
+For an example of a PR adding an error code, see [#76143].
+
+[#76143]: https://github.com/rust-lang/rust/pull/76143
diff --git a/src/doc/rustc-dev-guide/src/external-repos.md b/src/doc/rustc-dev-guide/src/external-repos.md
new file mode 100644
index 000000000..533f7eb5e
--- /dev/null
+++ b/src/doc/rustc-dev-guide/src/external-repos.md
@@ -0,0 +1,113 @@
+# Using External Repositories
+
+The `rust-lang/rust` git repository depends on several other repos in the `rust-lang` organization.
+There are three main ways we use dependencies:
+1. As a Cargo dependency through crates.io (e.g. `rustc-rayon`)
+2. As a git subtree (e.g. `clippy`)
+3. As a git submodule (e.g. `cargo`)
+
+As a general rule, use crates.io for libraries that could be useful for others in the ecosystem; use
+subtrees for tools that depend on compiler internals and need to be updated if there are breaking
+changes; and use submodules for tools that are independent of the compiler.
+
+## External Dependencies (subtree)
+
+As a developer to this repository, you don't have to treat the following external projects
+differently from other crates that are directly in this repo:
+
+* [Clippy](https://github.com/rust-lang/rust-clippy)
+* [Miri]
+* [rustfmt](https://github.com/rust-lang/rustfmt)
+* [rust-analyzer](https://github.com/rust-lang/rust-analyzer)
+
+[Miri]: https://github.com/rust-lang/miri
+
+In contrast to `submodule` dependencies
+(see below for those), the `subtree` dependencies are just regular files and directories which can
+be updated in tree. However, if possible, enhancements, bug fixes, etc. specific
+to these tools should be filed against the tools directly in their respective
+upstream repositories. The exception is that when rustc changes are required to
+implement a new tool feature or test, that should happen in one collective rustc PR.
+
+### Synchronizing a subtree
+
+Periodically the changes made to subtree based dependencies need to be synchronized between this
+repository and the upstream tool repositories.
+
+Subtree synchronizations are typically handled by the respective tool maintainers. Other users
+are welcome to submit synchronization PRs, however, in order to do so you will need to modify
+your local git installation and follow a very precise set of instructions.
+These instructions are documented, along with several useful tips and tricks, in the
+[syncing subtree changes][clippy-sync-docs] section in Clippy's Contributing guide.
+The instructions are applicable for use with any subtree based tool, just be sure to
+use the correct corresponding subtree directory and remote repository.
+
+The synchronization process goes in two directions: `subtree push` and `subtree pull`.
+
+A `subtree push` takes all the changes that happened to the copy in this repo and creates commits
+on the remote repo that match the local changes. Every local
+commit that touched the subtree causes a commit on the remote repo, but
+is modified to move the files from the specified directory to the tool repo root.
+
+A `subtree pull` takes all changes since the last `subtree pull`
+from the tool repo and adds these commits to the rustc repo along with a merge commit that moves
+the tool changes into the specified directory in the Rust repository.
+
+It is recommended that you always do a push first and get that merged to the tool master branch.
+Then, when you do a pull, the merge works without conflicts.
+While it's definitely possible to resolve conflicts during a pull, you may have to redo the conflict
+resolution if your PR doesn't get merged fast enough and there are new conflicts. Do not try to
+rebase the result of a `git subtree pull`, rebasing merge commits is a bad idea in general.
+
+You always need to specify the `-P` prefix to the subtree directory and the corresponding remote
+repository. If you specify the wrong directory or repository
+you'll get very fun merges that try to push the wrong directory to the wrong remote repository.
+Luckily you can just abort this without any consequences by throwing away either the pulled commits
+in rustc or the pushed branch on the remote and try again. It is usually fairly obvious
+that this is happening because you suddenly get thousands of commits that want to be synchronized.
+
+[clippy-sync-docs]: https://doc.rust-lang.org/nightly/clippy/development/infrastructure/sync.html
+
+### Creating a new subtree dependency
+
+If you want to create a new subtree dependency from an existing repository, call (from this
+repository's root directory!)
+
+```
+git subtree add -P src/tools/clippy https://github.com/rust-lang/rust-clippy.git master
+```
+
+This will create a new commit, which you may not rebase under any circumstances! Delete the commit
+and redo the operation if you need to rebase.
+
+Now you're done, the `src/tools/clippy` directory behaves as if Clippy were
+part of the rustc monorepo, so no one but you (or others that synchronize
+subtrees) actually needs to use `git subtree`.
+
+
+## External Dependencies (submodules)
+
+Building Rust will also use external git repositories tracked using [git
+submodules]. The complete list may be found in the [`.gitmodules`] file. Some
+of these projects are required (like `stdarch` for the standard library) and
+some of them are optional (like `src/doc/book`).
+
+Usage of submodules is discussed more in the [Using Git chapter](git.md#git-submodules).
+
+Some of the submodules are allowed to be in a "broken" state where they
+either don't build or their tests don't pass, e.g. the documentation books
+like [The Rust Reference]. Maintainers of these projects will be notified
+when the project is in a broken state, and they should fix them as soon
+as possible. The current status is tracked on the [toolstate website].
+More information may be found on the Forge [Toolstate chapter].
+In practice, it is very rare for documentation to have broken toolstate.
+
+Breakage is not allowed in the beta and stable channels, and must be addressed
+before the PR is merged. They are also not allowed to be broken on master in
+the week leading up to the beta cut.
+
+[git submodules]: https://git-scm.com/book/en/v2/Git-Tools-Submodules
+[`.gitmodules`]: https://github.com/rust-lang/rust/blob/master/.gitmodules
+[The Rust Reference]: https://github.com/rust-lang/reference/
+[toolstate website]: https://rust-lang-nursery.github.io/rust-toolstate/
+[Toolstate chapter]: https://forge.rust-lang.org/infra/toolstate.html
diff --git a/src/doc/rustc-dev-guide/src/fuzzing.md b/src/doc/rustc-dev-guide/src/fuzzing.md
new file mode 100644
index 000000000..3fb1add01
--- /dev/null
+++ b/src/doc/rustc-dev-guide/src/fuzzing.md
@@ -0,0 +1,149 @@
+# Fuzzing
+
+<!-- date-check: Mar 2023 -->
+
+For the purposes of this guide, *fuzzing* is any testing methodology that
+involves compiling a wide variety of programs in an attempt to uncover bugs in
+rustc. Fuzzing is often used to find internal compiler errors (ICEs). Fuzzing
+can be beneficial, because it can find bugs before users run into them and
+provide small, self-contained programs that make the bug easier to track down.
+However, some common mistakes can reduce the helpfulness of fuzzing and end up
+making contributors' lives harder. To maximize your positive impact on the Rust
+project, please read this guide before reporting fuzzer-generated bugs!
+
+## Guidelines
+
+### In a nutshell
+
+*Please do:*
+
+- Ensure the bug is still present on the latest nightly rustc
+- Include a reasonably minimal, standalone example along with any bug report
+- Include all of the information requested in the bug report template
+- Search for existing reports with the same message and query stack
+- Format the test case with `rustfmt`, if it maintains the bug
+- Indicate that the bug was found by fuzzing
+
+*Please don't:*
+
+- Don't report lots of bugs that use internal features, including but not
+  limited to `custom_mir`, `lang_items`, `no_core`, and `rustc_attrs`.
+- Don't seed your fuzzer with inputs that are known to crash rustc (details
+  below).
+
+### Discussion
+
+If you're not sure whether or not an ICE is a duplicate of one that's already
+been reported, please go ahead and report it and link to issues you think might
+be related. In general, ICEs on the same line but with different *query stacks*
+are usually distinct bugs. For example, [#109020][#109202] and [#109129][#109129]
+had similar error messages:
+
+```
+error: internal compiler error: compiler/rustc_middle/src/ty/normalize_erasing_regions.rs:195:90: Failed to normalize <[closure@src/main.rs:36:25: 36:28] as std::ops::FnOnce<(Emplacable<()>,)>>::Output, maybe try to call `try_normalize_erasing_regions` instead
+```
+```
+error: internal compiler error: compiler/rustc_middle/src/ty/normalize_erasing_regions.rs:195:90: Failed to normalize <() as Project>::Assoc, maybe try to call `try_normalize_erasing_regions` instead
+```
+but different query stacks:
+```
+query stack during panic:
+#0 [fn_abi_of_instance] computing call ABI of `<[closure@src/main.rs:36:25: 36:28] as core::ops::function::FnOnce<(Emplacable<()>,)>>::call_once - shim(vtable)`
+end of query stack
+```
+```
+query stack during panic:
+#0 [check_mod_attrs] checking attributes in top-level module
+#1 [analysis] running analysis passes on this crate
+end of query stack
+```
+
+[#109020]: https://github.com/rust-lang/rust/issues/109020
+[#109129]: https://github.com/rust-lang/rust/issues/109129
+
+## Building a corpus
+
+When building a corpus, be sure to avoid collecting tests that are already
+known to crash rustc. A fuzzer that is seeded with such tests is more likely to
+generate bugs with the same root cause, wasting everyone's time. The simplest
+way to avoid this is to loop over each file in the corpus, see if it causes an
+ICE, and remove it if so.
+
+To build a corpus, you may want to use:
+
+- The rustc/rust-analyzer/clippy test suites (or even source code) --- though avoid
+  tests that are already known to cause failures, which often begin with comments
+  like `// failure-status: 101` or `// known-bug: #NNN`.
+- The already-fixed ICEs in [Glacier][glacier] --- though avoid the unfixed
+  ones in `ices/`!
+
+## Extra credit
+
+Here are a few things you can do to help the Rust project after filing an ICE.
+
+- [Bisect][bisect] the bug to figure out when it was introduced 
+- Fix "distractions": problems with the test case that don't contribute to
+  triggering the ICE, such as syntax errors or borrow-checking errors
+- Minimize the test case (see below)
+- Add the minimal test case to [Glacier][glacier]
+
+[bisect]: https://rust-lang.github.io/cargo-bisect-rustc/
+
+## Minimization
+
+It is helpful to carefully *minimize* the fuzzer-generated input. When
+minimizing, be careful to preserve the original error, and avoid introducing
+distracting problems such as syntax, type-checking, or borrow-checking errors.
+
+There are some tools that can help with minimization. If you're not sure how
+to avoid introducing syntax, type-, and borrow-checking errors while using
+these tools, post both the complete and minimized test cases. Generally,
+*syntax-aware* tools give the best results in the least amount of time.
+[`treereduce-rust`][treereduce] and [picireny][picireny] are syntax-aware.
+`halfempty` is not, but is generally a high-quality tool.
+
+[halfempty]: https://github.com/googleprojectzero/halfempty
+[picireny]: https://github.com/renatahodovan/picireny
+[treereduce]: https://github.com/langston-barrett/treereduce
+
+## Effective fuzzing
+
+When fuzzing rustc, you may want to avoid generating machine code, since this
+is mostly done by LLVM. Try `--emit=mir` instead.
+
+A variety of compiler flags can uncover different issues. `-Zmir-opt-level=4`
+will turn on MIR optimization passes that are not run by default, potentially
+uncovering interesting bugs. `-Zvalidate-mir` can help uncover such bugs.
+
+If you're fuzzing a compiler you built, you may want to build it with `-C
+target-cpu=native` or even PGO/BOLT to squeeze out a few more executions per
+second. Of course, it's best to try multiple build configurations and see
+what actually results in superior throughput.
+
+You may want to build rustc from source with debug assertions to find
+additional bugs, though this is a trade-off: it can slow down fuzzing by
+requiring extra work for every execution. To enable debug assertions, add this
+to `config.toml` when compiling rustc:
+
+```toml
+[rust]
+debug-assertions = true
+```
+
+ICEs that require debug assertions to reproduce should be tagged 
+[`requires-debug-assertions`][requires-debug-assertions].
+
+[requires-debug-assertions]: https://github.com/rust-lang/rust/labels/requires-debug-assertions
+
+## Existing projects
+
+- [fuzz-rustc][fuzz-rustc] demonstrates how to fuzz rustc with libfuzzer
+- [icemaker][icemaker] runs rustc and other tools on a large number of source
+  files with a variety of flags to catch ICEs
+- [tree-splicer][tree-splicer] generates new source files by combining existing
+  ones while maintaining correct syntax
+
+[glacier]: https://github.com/rust-lang/glacier
+[fuzz-rustc]: https://github.com/dwrensha/fuzz-rustc
+[icemaker]: https://github.com/matthiaskrgr/icemaker/
+[tree-splicer]: https://github.com/langston-barrett/tree-splicer/
\ No newline at end of file
diff --git a/src/doc/rustc-dev-guide/src/generics.md b/src/doc/rustc-dev-guide/src/generics.md
index 0173bee8f..7512b3b47 100644
--- a/src/doc/rustc-dev-guide/src/generics.md
+++ b/src/doc/rustc-dev-guide/src/generics.md
@@ -6,7 +6,7 @@ inference, type checking, and trait solving. Conceptually, during these routines
 that one type is equal to another type and want to swap one out for the other and then swap that out
 for another type and so on until we eventually get some concrete types (or an error).
 
-In rustc this is done using the `SubstsRef` that we mentioned above (“substs” = “substitutions”).
+In rustc this is done using [SubstsRef] (“substs” = “substitutions”).
 Conceptually, you can think of `SubstsRef` as a list of types that are to be substituted for the
 generic type parameters of the ADT.
 
@@ -18,6 +18,7 @@ is conceptually like a `&'tcx [GenericArgKind<'tcx>]` slice (but it is actually
 [list]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/struct.List.html
 [`GenericArg`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/subst/struct.GenericArg.html
 [`GenericArgKind`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/subst/enum.GenericArgKind.html
+[SubstsRef]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/subst/type.SubstsRef.html
 
 So why do we use this `List` type instead of making it really a slice? It has the length "inline",
 so `&List` is only 32 bits. As a consequence, it cannot be "subsliced" (that only works if the
@@ -126,7 +127,7 @@ You may have a couple of followup questions…
 
 **`subst`** How do we actually do the substitutions? There is a function for that too! You use
 [`subst`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/subst/struct.EarlyBinder.html#method.subst) to
-replace a `SubstRef` with another list of types.
+replace a `SubstsRef` with another list of types.
 
 [Here is an example of actually using `subst` in the compiler][substex].  The exact details are not
 too important, but in this piece of code, we happen to be converting from the `rustc_hir::Ty` to
diff --git a/src/doc/rustc-dev-guide/src/getting-started.md b/src/doc/rustc-dev-guide/src/getting-started.md
index bc294d1b3..d5c948994 100644
--- a/src/doc/rustc-dev-guide/src/getting-started.md
+++ b/src/doc/rustc-dev-guide/src/getting-started.md
@@ -1,13 +1,37 @@
 # Getting Started
 
+Thank you for your interest in contributing to Rust! There are many ways to
+contribute, and we appreciate all of them.
+
 <!-- toc -->
 
+If this is your first time contributing, the [walkthrough] chapter can give you a good example of
+how a typical contribution would go.
+
 This documentation is _not_ intended to be comprehensive; it is meant to be a
 quick guide for the most useful things. For more information, [see this
 chapter on how to build and run the compiler](./building/how-to-build-and-run.md).
 
+[internals]: https://internals.rust-lang.org
+[rust-discord]: http://discord.gg/rust-lang
+[rust-zulip]: https://rust-lang.zulipchat.com
+[coc]: https://www.rust-lang.org/conduct.html
+[walkthrough]: ./walkthrough.md
+[Getting Started]: ./getting-started.md
+
 ## Asking Questions
 
+If you have questions, please make a post on the [Rust Zulip server][rust-zulip] or
+[internals.rust-lang.org][internals]. If you are contributing to Rustup, be aware they are not on
+Zulip - you can ask questions in `#wg-rustup` [on Discord][rust-discord].
+See the [list of teams and working groups][governance] and [the Community page][community] on the
+official website for more resources.
+
+[governance]: https://www.rust-lang.org/governance
+[community]: https://www.rust-lang.org/community
+
+As a reminder, all contributors are expected to follow our [Code of Conduct][coc].
+
 The compiler team (or `t-compiler`) usually hangs out in Zulip [in this
 "stream"][z]; it will be easiest to get questions answered there.
 
@@ -30,6 +54,12 @@ compiler, [consult this "experts map"][map].
 It's not perfectly complete, though, so please also feel free to ask questions
 even if you can't figure out who to ping.
 
+Another way to find experts for a given part of the compiler is to see who has made recent commits.
+For example, to find people who have recently worked on name resolution since the 1.68.2 release,
+you could run `git shortlog -n 1.68.2.. compiler/rustc_resolve/`. Ignore any commits starting with
+"Rollup merge" or commits by `@bors` (see [CI contribution prodcedures](./contributing.md#ci) for
+more information about these commits).
+
 [map]: https://github.com/rust-lang/compiler-team/blob/master/content/experts/map.toml
 
 ### Etiquette
@@ -42,91 +72,61 @@ Just pinging someone without providing any context can be a bit annoying and
 just create noise, so we ask that you be mindful of the fact that the
 `t-compiler` folks get a lot of pings in a day.
 
-## Cloning and Building
-
-### System Requirements
-
-Internet access is required.
-
-The most notable software requirement is that you will need Python 2 or 3, but
-there are various others.
-
-The following hardware is recommended.
-* 30GB+ of free disk space.
-* 8GB+ RAM
-* 2+ cores
-
-More powerful machines will lead to much faster builds. There are various
-strategies to work around lesser hardware in the following chapters.
-
-See [this chapter][prereqs] for more details about software and hardware prerequisites.
-
-[prereqs]: ./building/prerequisites.md
+## What should I work on?
 
-### Cloning
+The Rust project is quite large and it can be difficult to know which parts of the project need
+help, or are a good starting place for beginners. Here are some suggested starting places.
 
-You can just do a normal git clone:
+### Easy or mentored issues
 
-```sh
-git clone https://github.com/rust-lang/rust.git
-cd rust
-```
+If you're looking for somewhere to start, check out the following [issue
+search][help-wanted-search]. See the [Triage] for an explanation of these labels. You can also try
+filtering the search to areas you're interested in. For example:
 
-### `x.py` Intro
+- `repo:rust-lang/rust-clippy` will only show clippy issues
+- `label:T-compiler` will only show issues related to the compiler
+- `label:A-diagnostics` will only show diagnostic issues
 
-`rustc` is a [bootstrapping] compiler, which makes it more complex than a
-typical Rust program. As a result, you cannot use Cargo to build it. Instead
-you must use the special tool `x.py`. It is used for the things Cargo is
-normally used for: building, testing, creating releases, formatting, etc.
+Not all important or beginner work has issue labels.
+See below for how to find work that isn't labelled.
 
-[bootstrapping]: ./building/bootstrapping.md
+[help-wanted-search]: https://github.com/issues?q=is%3Aopen+is%3Aissue+org%3Arust-lang+no%3Aassignee+label%3AE-easy%2C%22good+first+issue%22%2Cgood-first-issue%2CE-medium%2CE-help-wanted%2CE-mentor
+[Triage]: ./contributing.md#issue-triage
 
-### Configuring the compiler
+### Recurring work
 
-In the top level of the repo:
+Some work is too large to be done by a single person. In this case, it's common to have "Tracking
+issues" to co-ordinate the work between contributors. Here are some example tracking issues where
+it's easy to pick up work without a large time commitment:
 
-```sh
-$ ./x.py setup
-```
+- [Rustdoc Askama Migration](https://github.com/rust-lang/rust/issues/108868)
+- [Diagnostic Translation](https://github.com/rust-lang/rust/issues/100717)
+- [Move UI tests to subdirectories](https://github.com/rust-lang/rust/issues/73494)
 
-This will do some initialization and walk you through an interactive setup to
-create `config.toml`, the primary configuration file.
+If you find more recurring work, please feel free to add it here!
 
-See [this chapter][config] for more info about configuration.
+### Clippy issues
 
-[config]: ./building/how-to-build-and-run.md#create-a-configtoml
+The [Clippy] project has spent a long time making its contribution process as friendly to newcomers
+as possible. Consider working on it first to get familiar with the process and the compiler
+internals.
 
-### Common `x.py` commands
+See [the Clippy contribution guide][clippy-contributing] for instructions on getting started.
 
-Here are the basic invocations of the `x.py` commands most commonly used when
-working on `rustc`, `std`, `rustdoc`, and other tools.
+[Clippy]: https://doc.rust-lang.org/clippy/
+[clippy-contributing]: https://github.com/rust-lang/rust-clippy/blob/master/CONTRIBUTING.md
 
-| Command | When to use it |
-| --- | --- |
-| `./x.py check` | Quick check to see if most things compile; [rust-analyzer can run this automatically for you][rust-analyzer] |
-| `./x.py build` | Builds `rustc`, `std`, and `rustdoc` |
-| `./x.py test` | Runs all tests |
-| `./x.py fmt` | Formats all code |
+### Diagnostic issues
 
-As written, these commands are reasonable starting points. However, there are
-additional options and arguments for each of them that are worth learning for
-serious development work. In particular, `./x.py build` and `./x.py test`
-provide many ways to compile or test a subset of the code, which can save a lot
-of time.
+Many diagnostic issues are self-contained and don't need detailed background knowledge of the
+compiler. You can see a list of diagnostic issues [here][diagnostic-issues].
 
-Also, note that `x.py` supports all kinds of path suffixes for `compiler`, `library`,
-and `src/tools` directories. So, you can simply run `x.py test tidy` instead of
-`x.py test src/tools/tidy`. Or, `x.py build std` instead of `x.py build library/std`.
-
-[rust-analyzer]: ./building/suggested.html#configuring-rust-analyzer-for-rustc
-
-See the chapters on [building](./building/how-to-build-and-run.md),
-[testing](./tests/intro.md), and [rustdoc](./rustdoc.md) for more details.
+[diagnostic-issues]: https://github.com/rust-lang/rust/issues?q=is%3Aissue+is%3Aopen+label%3AA-diagnostics+no%3Aassignee
 
 ### Contributing code to other Rust projects
 
 There are a bunch of other projects that you can contribute to outside of the
-`rust-lang/rust` repo, including `clippy`, `miri`, `chalk`, and many others.
+`rust-lang/rust` repo, including `cargo`, `miri`, `rustup`, and many others.
 
 These repos might have their own contributing guidelines and procedures. Many
 of them are owned by working groups (e.g. `chalk` is largely owned by
@@ -146,173 +146,37 @@ incredibly helpful:
 - [Writing documentation][wd]: if you are feeling a bit more intrepid, you could try
   to read a part of the code and write doc comments for it. This will help you
   to learn some part of the compiler while also producing a useful artifact!
+- [Triaging issues][triage]: categorizing, replicating, and minimizing issues is very helpful to the Rust maintainers.
 - [Working groups][wg]: there are a bunch of working groups on a wide variety
   of rust-related things.
+- Answer questions in the _Get Help!_ channels on the [Rust Discord
+  server][rust-discord], on [users.rust-lang.org][users], or on
+  [StackOverflow][so].
+- Participate in the [RFC process](https://github.com/rust-lang/rfcs).
+- Find a [requested community library][community-library], build it, and publish
+  it to [Crates.io](http://crates.io). Easier said than done, but very, very
+  valuable!
+
+[rust-discord]: https://discord.gg/rust-lang
+[users]: https://users.rust-lang.org/
+[so]: http://stackoverflow.com/questions/tagged/rust
+[community-library]: https://github.com/rust-lang/rfcs/labels/A-community-library
 
 [iceb]: ./notification-groups/cleanup-crew.md
 [wd]: ./contributing.md#writing-documentation
 [wg]: https://rust-lang.github.io/compiler-team/working-groups/
+[triage]: ./contributing.md#issue-triage
 
-## Contributor Procedures
-
-There are some official procedures to know about. This is a tour of the
-highlights, but there are a lot more details, which we will link to below.
-
-### Code Review
-
-When you open a PR on the `rust-lang/rust` repo, a bot called `@rustbot` will
-automatically assign a reviewer to the PR based on which files you changed.
-The reviewer is the person that will approve the PR to be tested and merged.
-If you want a specific reviewer (e.g. a team member you've been working with),
-you can specifically request them by writing `r? @user` (e.g. `r? @jyn514`) in
-either the original post or a followup comment
-(you can see [this comment][r?] for example).
-
-Please note that the reviewers are humans, who for the most part work on `rustc`
-in their free time. This means that they can take some time to respond and review
-your PR. It also means that reviewers can miss some PRs that are assigned to them.
-
-To try to move PRs forward, the Triage WG regularly goes through all PRs that
-are waiting for review and haven't been discussed for at least 2 weeks. If you
-don't get a review within 2 weeks, feel free to ask the Triage WG on
-Zulip ([#t-release/triage]). They have knowledge of when to ping, who might be
-on vacation, etc.
-
-The reviewer may request some changes using the GitHub code review interface.
-They may also request special procedures (such as a [crater] run; [see
-below][break]) for some PRs.
-
-[r?]: https://github.com/rust-lang/rust/pull/78133#issuecomment-712692371
-[#t-release/triage]: https://rust-lang.zulipchat.com/#narrow/stream/242269-t-release.2Ftriage
-[break]: #breaking-changes
-
-When the PR is ready to be merged, the reviewer will issue a command to
-`@bors`, the CI bot. Usually, this is `@bors r+` or `@bors r=user` to approve
-a PR (there are few other commands, but they are less relevant here).
-You can see [this comment][r+] for example. This puts the PR in [bors's queue][bors]
-to be tested and merged. Be patient; this can take a while and the queue can
-sometimes be long. PRs are never merged by hand.
-
-[r+]: https://github.com/rust-lang/rust/pull/78133#issuecomment-712726339
-[bors]: https://bors.rust-lang.org/queue/rust
-
-### Bug Fixes or "Normal" code changes
-
-For most PRs, no special procedures are needed. You can just open a PR, and it
-will be reviewed, approved, and merged. This includes most bug fixes,
-refactorings, and other user-invisible changes. The next few sections talk
-about exceptions to this rule.
-
-Also, note that it is perfectly acceptable to open WIP PRs or GitHub [Draft
-PRs][draft]. Some people prefer to do this so they can get feedback along the
-way or share their code with a collaborator. Others do this so they can utilize
-the CI to build and test their PR (e.g. if you are developing on a laptop).
-
-[draft]: https://github.blog/2019-02-14-introducing-draft-pull-requests/
-
-### New Features
-
-Rust has strong backwards-compatibility guarantees. Thus, new features can't
-just be implemented directly in stable Rust. Instead, we have 3 release
-channels: stable, beta, and nightly.
-
-- **Stable**: this is the latest stable release for general usage.
-- **Beta**: this is the next release (will be stable within 6 weeks).
-- **Nightly**: follows the `master` branch of the repo. This is the only
-  channel where unstable, incomplete, or experimental features are usable with
-  feature gates.
-
-In order to implement a new feature, usually you will need to go through [the
-RFC process][rfc] to propose a design, have discussions, etc. In some cases,
-small features can be added with only an FCP ([see below][break]). If in doubt, ask the
-compiler, language, or libs team (whichever is most relevant).
-
-[rfc]: https://github.com/rust-lang/rfcs/blob/master/README.md
-
-After a feature is approved to be added, a tracking issue is created on the
-`rust-lang/rust` repo, which tracks the progress towards the implementation of
-the feature, any bugs reported, and eventually stabilization.
-
-The feature then needs to be implemented behind a feature gate, which prevents
-it from being accidentally used.
-
-Finally, somebody may propose stabilizing the feature in an upcoming version of
-Rust. This requires a Final Comment Period ([see below][break]) to get the
-approval of the relevant teams.
-
-After that, the feature gate can be removed and the feature turned on for all users.
-
-For more details on this process, see [this chapter on implementing new
-features.](./implementing_new_features.md)
-
-### Breaking Changes
-
-As mentioned above, Rust has strong backwards-compatibility guarantees. To this
-end, we are reluctant to make breaking changes. However, sometimes they are
-needed to correct compiler bugs (e.g. code that compiled but should not) or
-make progress on some features.
-
-Depending on the scale of the breakage, there are a few different actions that
-can be taken.  If the reviewer believes the breakage is very minimal (i.e. very
-unlikely to be actually encountered by users), they may just merge the change.
-More often, they will request a Final Comment Period (FCP), which calls for
-rough consensus among the members of a relevant team. The team members can
-discuss the issue and either accept, reject, or request changes on the PR.
-
-If the scale of breakage is large, a deprecation warning may be needed. This is
-a warning that the compiler will display to users whose code will break in the
-future. After some time, an FCP can be used to move forward with the actual
-breakage.
-
-If the scale of breakage is unknown, a team member or contributor may request a
-[crater] run. This is a bot that will compile all crates.io crates and many
-public github repos with the compiler with your changes. A report will then be
-generated with crates that ceased to compile with or began to compile with your
-changes. Crater runs can take a few days to complete.
-
-[crater]: https://github.com/rust-lang/crater
-
-### Major Changes
-
-The compiler team has a special process for large changes, whether or not they
-cause breakage. This process is called a Major Change Proposal (MCP). MCP is a
-relatively lightweight mechanism for getting feedback on large changes to the
-compiler (as opposed to a full RFC or a design meeting with the team).
-
-Example of things that might require MCPs include major refactorings, changes
-to important types, or important changes to how the compiler does something, or
-smaller user-facing changes.
-
-**When in doubt, ask on [zulip][z]. It would be a shame to put a lot of work
-into a PR that ends up not getting merged!** [See this document][mcpinfo] for
-more info on MCPs.
-
-[mcpinfo]: https://forge.rust-lang.org/compiler/mcp.html
-
-### Performance
-
-Compiler performance is important. We have put a lot of effort over the last
-few years into [gradually improving it][perfdash].
-
-[perfdash]: https://perf.rust-lang.org/dashboard.html
+## Cloning and Building
 
-If you suspect that your change may cause a performance regression (or
-improvement), you can request a "perf run" (your reviewer may also request one
-before approving). This is yet another bot that will compile a collection of
-benchmarks on a compiler with your changes. The numbers are reported
-[here][perf], and you can see a comparison of your changes against the latest
-master.
+See ["How to build and run the compiler"](./building//how-to-build-and-run.md).
 
-For an introduction to the performance of Rust code in general
-which would also be useful in rustc development, see [The Rust Performance Book].
+## Contributor Procedures
 
-[perf]: https://perf.rust-lang.org
-[The Rust Performance Book]: https://nnethercote.github.io/perf-book/
+This section has moved to the ["Contribution Procedures"](./contributing.md) chapter.
 
 ## Other Resources
 
-- This guide: talks about how `rustc` works
-- [The t-compiler zulip][z]
-- [The compiler's documentation (rustdocs)](https://doc.rust-lang.org/nightly/nightly-rustc/)
-- [The Forge](https://forge.rust-lang.org/) has more documentation about various procedures.
-- `#contribute` and `#rustdoc` on [Discord](https://discord.gg/rust-lang).
+This section has moved to the ["About this guide"][more-links] chapter.
+
+[more-links]: ./about-this-guide.md#other-places-to-find-information
diff --git a/src/doc/rustc-dev-guide/src/git.md b/src/doc/rustc-dev-guide/src/git.md
index a426157a2..34f2f101e 100644
--- a/src/doc/rustc-dev-guide/src/git.md
+++ b/src/doc/rustc-dev-guide/src/git.md
@@ -508,6 +508,18 @@ See [the docs for `--color-moved`](https://git-scm.com/docs/git-diff#Documentati
 See [the relevant section for PR authors](#git-range-diff). This can be useful for comparing code
 that was force-pushed to make sure there are no unexpected changes.
 
+### Ignoring changes to specific files
+
+Many large files in the repo are autogenerated. To view a diff that ignores changes to those files,
+you can use the following syntax (e.g. Cargo.lock):
+
+```
+git log -p ':!Cargo.lock'
+```
+
+Arbitrary patterns are supported (e.g. `:!compiler/*`). Patterns use the same syntax as
+`.gitignore`, with `:` prepended to indicate a pattern.
+
 ## Git submodules
 
 **NOTE**: submodules are a nice thing to know about, but it *isn't* an absolute
diff --git a/src/doc/rustc-dev-guide/src/identifiers.md b/src/doc/rustc-dev-guide/src/identifiers.md
index 1b60b3b0b..09e85c019 100644
--- a/src/doc/rustc-dev-guide/src/identifiers.md
+++ b/src/doc/rustc-dev-guide/src/identifiers.md
@@ -65,8 +65,7 @@ See the [HIR chapter][hir-map] for more detailed information.
 
 - [`BasicBlock`] identifies a *basic block*. It points to an instance of
   [`BasicBlockData`], which can be retrieved by indexing into
-  [`Body::basic_blocks()`] (note that you must call a function; the field is
-  private).
+  [`Body.basic_blocks`].
 
 - [`Local`] identifies a local variable in a function. Its associated data is in
   [`LocalDecl`], which can be retrieved by indexing into [`Body.local_decls`].
@@ -93,7 +92,7 @@ See the [HIR chapter][hir-map] for more detailed information.
 
 [`BasicBlock`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/struct.BasicBlock.html
 [`BasicBlockData`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/struct.BasicBlockData.html
-[`Body::basic_blocks()`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/struct.Body.html#method.basic_blocks
+[`Body.basic_blocks`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/struct.Body.html#structfield.basic_blocks
 [`Local`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/struct.Local.html
 [`LocalDecl`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/struct.LocalDecl.html
 [`Body.local_decls`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/struct.Body.html#structfield.local_decls
diff --git a/src/doc/rustc-dev-guide/src/implementing_new_features.md b/src/doc/rustc-dev-guide/src/implementing_new_features.md
index 9bd853080..946637d29 100644
--- a/src/doc/rustc-dev-guide/src/implementing_new_features.md
+++ b/src/doc/rustc-dev-guide/src/implementing_new_features.md
@@ -1,5 +1,7 @@
 # Implementing new features
 
+<!-- toc -->
+
 When you want to implement a new significant feature in the compiler,
 you need to go through this process to make sure everything goes
 smoothly.
diff --git a/src/doc/rustc-dev-guide/src/mir/index.md b/src/doc/rustc-dev-guide/src/mir/index.md
index 0c00928c0..dc0be167b 100644
--- a/src/doc/rustc-dev-guide/src/mir/index.md
+++ b/src/doc/rustc-dev-guide/src/mir/index.md
@@ -217,7 +217,7 @@ over the overflow checks.)
 ## MIR data types
 
 The MIR data types are defined in the [`compiler/rustc_middle/src/mir/`][mir]
-module.  Each of the key concepts mentioned in the previous section
+module. Each of the key concepts mentioned in the previous section
 maps in a fairly straightforward way to a Rust type.
 
 The main MIR data type is [`Body`]. It contains the data for a single
@@ -233,15 +233,14 @@ but [you can read about those below](#promoted)).
 - **Terminators** are represented by the [`Terminator`].
 - **Locals** are represented by a [newtype'd] index type [`Local`].
   The data for a local variable is found in the
-  [`Body::local_decls`][localdecls] vector). There is also a special constant
+  [`Body::local_decls`][localdecls] vector. There is also a special constant
   [`RETURN_PLACE`] identifying the special "local" representing the return value.
-- **Places** are identified by the enum [`Place`]. There are a few
-  variants:
+- **Places** are identified by the struct [`Place`]. There are a few
+  fields:
   - Local variables like `_1`
-  - Static variables `FOO`
   - **Projections**, which are fields or other things that "project
-    out" from a base place. These are represented by the type
-    [`ProjectionElem`].  So e.g. the place `_1.f` is a projection,
+    out" from a base place. These are represented by the [newtype'd] type
+    [`ProjectionElem`]. So e.g. the place `_1.f` is a projection,
     with `f` being the "projection element" and `_1` being the base
     path. `*_1` is also a projection, with the `*` being represented
     by the [`ProjectionElem::Deref`] element.
diff --git a/src/doc/rustc-dev-guide/src/notification-groups/cleanup-crew.md b/src/doc/rustc-dev-guide/src/notification-groups/cleanup-crew.md
index 436b51fd1..2e7b1766c 100644
--- a/src/doc/rustc-dev-guide/src/notification-groups/cleanup-crew.md
+++ b/src/doc/rustc-dev-guide/src/notification-groups/cleanup-crew.md
@@ -77,38 +77,13 @@ various builds of rustc. For recent regressions, it is even able to
 use the builds from our CI to track down the regression to a specific
 PR; for older regressions, it will simply identify a nightly.
 
-To learn to use [cargo-bisect-rustc], check out [this blog
-post][learn], which gives a quick introduction to how it works. You
-can also ask questions at the Zulip stream
-[`#t-compiler/cargo-bisect-rustc`][zcbr], or help in improving the tool.
+To learn to use [cargo-bisect-rustc], check out [this blog post][learn], which
+gives a quick introduction to how it works. Additionally, there is a [Guide]
+which goes into more detail on how to use it. You can also ask questions at
+the Zulip stream [`#t-compiler/cargo-bisect-rustc`][zcbr], or help in
+improving the tool.
 
 [cargo-bisect-rustc]: https://github.com/rust-lang/cargo-bisect-rustc/
 [learn]: https://blog.rust-lang.org/inside-rust/2019/12/18/bisecting-rust-compiler.html
 [zcbr]: https://rust-lang.zulipchat.com/#narrow/stream/217417-t-compiler.2Fcargo-bisect-rustc
-
-### identifying the range of PRs in a nightly
-
-If the regression occurred more than 90 days ago, then
-cargo-bisect-rustc will not able to identify the particular PR that
-caused the regression, just the nightly build. In that case, we can
-identify the set of PRs that this corresponds to by using the git
-history. 
-
-The command `rustc +nightly -vV` will cause rustc to output a number
-of useful bits of version info, including the `commit-hash`. Given the
-commit-hash of two nightly versions, you can find all of PRs that have
-landed in between by taking the following steps:
-
-1. Go to an update checkout of the [rust-lang/rust] repository
-2. Execute the command `git log --author=bors --format=oneline SHA1..SHA2`
-  * This will list out all of the commits by bors, which is our merge bot
-  * Each commit corresponds to one PR, and information about the PR should be in the description
-3. Copy and paste that information into the bug report
-
-Often, just eye-balling the PR descriptions (which are included in the
-commit messages) will give you a good idea which one likely caused the
-problem. But if you're unsure feel free to just ping the compiler team
-(`@rust-lang/compiler`) or else to ping the authors of the PR
-themselves.
-
-[rust-lang/rust]: https://github.com/rust-lang/rust/
+[Guide]: https://rust-lang.github.io/cargo-bisect-rustc/
diff --git a/src/doc/rustc-dev-guide/src/rustc-driver-getting-diagnostics.md b/src/doc/rustc-dev-guide/src/rustc-driver-getting-diagnostics.md
index 3c2102a50..47b9fb5d9 100644
--- a/src/doc/rustc-dev-guide/src/rustc-driver-getting-diagnostics.md
+++ b/src/doc/rustc-dev-guide/src/rustc-driver-getting-diagnostics.md
@@ -7,7 +7,7 @@
 To get diagnostics from the compiler,
 configure `rustc_interface::Config` to output diagnostic to a buffer,
 and run `TyCtxt.analysis`. The following was tested
-with <!-- date-check: Feb 2023 --> `nightly-2023-02-13`:
+with <!-- date-check: mar 2023 --> `nightly-2023-03-27`:
 
 ```rust
 {{#include ../examples/rustc-driver-getting-diagnostics.rs}}
diff --git a/src/doc/rustc-dev-guide/src/rustc-driver-interacting-with-the-ast.md b/src/doc/rustc-dev-guide/src/rustc-driver-interacting-with-the-ast.md
index d058a5838..4edbbca00 100644
--- a/src/doc/rustc-dev-guide/src/rustc-driver-interacting-with-the-ast.md
+++ b/src/doc/rustc-dev-guide/src/rustc-driver-interacting-with-the-ast.md
@@ -5,7 +5,7 @@
 ## Getting the type of an expression
 
 To get the type of an expression, use the `global_ctxt` to get a `TyCtxt`.
-The following was tested with <!-- date-check: Feb 2023 --> `nightly-2023-02-13`:
+The following was tested with <!-- date-check: mar 2023 --> `nightly-2023-03-27`:
 
 ```rust
 {{#include ../examples/rustc-driver-interacting-with-the-ast.rs}}
diff --git a/src/doc/rustc-dev-guide/src/rustdoc-internals.md b/src/doc/rustc-dev-guide/src/rustdoc-internals.md
index a8cc0c376..d58c2d280 100644
--- a/src/doc/rustc-dev-guide/src/rustdoc-internals.md
+++ b/src/doc/rustc-dev-guide/src/rustdoc-internals.md
@@ -7,38 +7,61 @@ see the ["Rustdoc overview" chapter](./rustdoc.md).
 
 ## From crate to clean
 
-In `core.rs` are two central items: the `DocContext` struct, and the `run_core`
-function. The latter is where rustdoc calls out to rustc to compile a crate to
-the point where rustdoc can take over. The former is a state container used
-when crawling through a crate to gather its documentation.
+In `core.rs` are two central items: the `DocContext` struct, and the
+`run_global_ctxt` function. The latter is where rustdoc calls out to rustc to
+compile a crate to the point where rustdoc can take over. The former is a state
+container used when crawling through a crate to gather its documentation.
 
 The main process of crate crawling is done in `clean/mod.rs` through several
-implementations of the `Clean` trait defined within. This is a conversion
-trait, which defines one method:
+functions with names that start with `clean_`. Each function accepts an `hir`
+or `ty` data structure, and outputs a `clean` structure used by rustdoc. For
+example, this function for converting lifetimes:
 
 ```rust,ignore
-pub trait Clean<T> {
-    fn clean(&self, cx: &DocContext) -> T;
+fn clean_lifetime<'tcx>(lifetime: &hir::Lifetime, cx: &mut DocContext<'tcx>) -> Lifetime {
+    let def = cx.tcx.named_bound_var(lifetime.hir_id);
+    if let Some(
+        rbv::ResolvedArg::EarlyBound(node_id)
+        | rbv::ResolvedArg::LateBound(_, _, node_id)
+        | rbv::ResolvedArg::Free(_, node_id),
+    ) = def
+    {
+        if let Some(lt) = cx.substs.get(&node_id).and_then(|p| p.as_lt()).cloned() {
+            return lt;
+        }
+    }
+    Lifetime(lifetime.ident.name)
 }
 ```
 
 `clean/mod.rs` also defines the types for the "cleaned" AST used later on to
-render documentation pages. Each usually accompanies an implementation of
-`Clean` that takes some AST or HIR type from rustc and converts it into the
+render documentation pages. Each usually accompanies a `clean` function
+that takes some AST or HIR type from rustc and converts it into the
 appropriate "cleaned" type. "Big" items like modules or associated items may
-have some extra processing in its `Clean` implementation, but for the most part
+have some extra processing in its `clean` function, but for the most part
 these impls are straightforward conversions. The "entry point" to this module
-is the `impl Clean<Crate> for visit_ast::RustdocVisitor`, which is called by
-`run_core` above.
-
-You see, I actually lied a little earlier: There's another AST transformation
-that happens before the events in `clean/mod.rs`. In `visit_ast.rs` is the
-type `RustdocVisitor`, which *actually* crawls a `rustc_hir::Crate` to get the first
-intermediate representation, defined in `doctree.rs`. This pass is mainly to
-get a few intermediate wrappers around the HIR types and to process visibility
-and inlining. This is where `#[doc(inline)]`, `#[doc(no_inline)]`, and
-`#[doc(hidden)]` are processed, as well as the logic for whether a `pub use`
-should get the full page or a "Reexport" line in the module page.
+is `clean::krate`, which is called by
+`run_global_ctxt` above.
+
+The first step in `clean::krate` is to invoke `visit_ast::RustdocVisitor` to
+process the module tree into an intermediate `visit_ast::Module`. This is the
+step that actually crawls the `rustc_hir::Crate`, normalizing various aspects
+of name resolution, such as:
+
+  * showing `#[macro_export]`-ed macros at the crate root, regardless of where
+    they're defined
+  * inlining public `use` exports of private items, or showing a "Reexport"
+    line in the module page
+  * inlining items with `#[doc(hidden)]` if the base item is hidden but the
+    reexport is not
+  * handling `#[doc(inline)]` and `#[doc(no_inline)]`
+  * handling import globs and cycles, so there are no duplicates or infinite
+    directory trees
+
+After this step, `clean::krate` invokes `clean_doc_module`, which actually
+converts the HIR items to the cleaned AST. This is also the step where cross-
+crate inlining is performed, which requires converting `rustc_middle` data
+structures into the cleaned AST instead.
 
 The other major thing that happens in `clean/mod.rs` is the collection of doc
 comments and `#[doc=""]` attributes into a separate field of the Attributes
@@ -48,41 +71,28 @@ easier to collect this documentation later in the process.
 The primary output of this process is a `clean::Crate` with a tree of Items
 which describe the publicly-documentable items in the target crate.
 
-### Hot potato
+### Passes anything but a gas station
+
+(alternate title: [hot potato](https://www.youtube.com/watch?v=WNFBIt5HxdY))
 
 Before moving on to the next major step, a few important "passes" occur over
-the documentation. These do things like combine the separate "attributes" into
-a single string to make the document easier on the markdown parser,
-or drop items that are not public or deliberately hidden with `#[doc(hidden)]`.
+the cleaned AST. Several of these passes are lints and reports, but some of
+them mutate or generate new items.
+
 These are all implemented in the `passes/` directory, one file per pass.
 By default, all of these passes are run on a crate, but the ones
 regarding dropping private/hidden items can be bypassed by passing
 `--document-private-items` to rustdoc. Note that unlike the previous set of AST
 transformations, the passes are run on the _cleaned_ crate.
 
-(Strictly speaking, you can fine-tune the passes run and even add your own, but
-[we're trying to deprecate that][44136]. If you need finer-grain control over
-these passes, please let us know!)
-
-[44136]: https://github.com/rust-lang/rust/issues/44136
-
-Here is the list of passes as of <!-- date-check --> November 2022:
+Here is the list of passes as of <!-- date-check --> March 2023:
 
 - `calculate-doc-coverage` calculates information used for the `--show-coverage`
   flag.
 
-- `check-bare-urls` detects links that are not linkified, e.g., in Markdown such as
-  `Go to https://example.com/.` It suggests wrapping the link with angle brackets:
-  `Go to <https://example.com/>.` to linkify it. This is the code behind the <!--
-  date: 2022-05 --> `rustdoc::bare_urls` lint.
-
-- `check-code-block-syntax` validates syntax inside Rust code blocks
-  (<code>```rust</code>)
-
-- `check-doc-test-visibility` runs doctest visibility–related lints.
-
-- `check-invalid-html-tags` detects invalid HTML (like an unclosed `<span>`)
-  in doc comments.
+- `check-doc-test-visibility` runs doctest visibility–related lints. This pass
+  runs before `strip-private`, which is why it needs to be separate from
+  `run-lints`.
 
 - `collect-intra-doc-links` resolves [intra-doc links](https://doc.rust-lang.org/nightly/rustdoc/write-documentation/linking-to-items-by-name.html).
 
@@ -92,44 +102,66 @@ Here is the list of passes as of <!-- date-check --> November 2022:
 
 - `propagate-doc-cfg` propagates `#[doc(cfg(...))]` to child items.
 
+- `run-lints` runs some of rustdoc's lints, defined in `passes/lint`. This is
+  the last pass to run.
+
+  - `bare_urls` detects links that are not linkified, e.g., in Markdown such as
+    `Go to https://example.com/.` It suggests wrapping the link with angle brackets:
+    `Go to <https://example.com/>.` to linkify it. This is the code behind the <!--
+    date-check: may 2022 --> `rustdoc::bare_urls` lint.
+  
+  - `check_code_block_syntax` validates syntax inside Rust code blocks
+    (<code>```rust</code>)
+
+  - `html_tags` detects invalid HTML (like an unclosed `<span>`)
+    in doc comments.
+
+- `strip-hidden` and `strip-private` strip all `doc(hidden)` and private items
+  from the output. `strip-private` implies `strip-priv-imports`. Basically, the
+  goal is to remove items that are not relevant for public documentation. This
+  pass is skipped when `--document-hidden-items` is passed.
+
 - `strip-priv-imports` strips all private import statements (`use`, `extern
   crate`) from a crate. This is necessary because rustdoc will handle *public*
   imports by either inlining the item's documentation to the module or creating
   a "Reexports" section with the import in it. The pass ensures that all of
-  these imports are actually relevant to documentation.
+  these imports are actually relevant to documentation. It is technically
+  only run when `--document-private-items` is passed, but `strip-private`
+  accomplishes the same thing.
 
-- `strip-hidden` and `strip-private` strip all `doc(hidden)` and private items
-  from the output. `strip-private` implies `strip-priv-imports`. Basically, the
-  goal is to remove items that are not relevant for public documentation.
+- `strip-private` strips all private items from a crate which cannot be seen
+  externally. This pass is skipped when `--document-private-items` is passed.
 
 There is also a `stripper` module in `passes/`, but it is a collection of
 utility functions for the `strip-*` passes and is not a pass itself.
 
-## From clean to crate
+## From clean to HTML
 
 This is where the "second phase" in rustdoc begins. This phase primarily lives
-in the `html/` folder, and it all starts with `run()` in `html/render.rs`. This
-code is responsible for setting up the `Context`, `SharedContext`, and `Cache`
-which are used during rendering, copying out the static files which live in
-every rendered set of documentation (things like the fonts, CSS, and JavaScript
-that live in `html/static/`), creating the search index, and printing out the
-source code rendering, before beginning the process of rendering all the
-documentation for the crate.
-
-Several functions implemented directly on `Context` take the `clean::Crate` and
-set up some state between rendering items or recursing on a module's child
-items. From here the "page rendering" begins, via an enormous `write!()` call
-in `html/layout.rs`. The parts that actually generate HTML from the items and
-documentation occurs within a series of `std::fmt::Display` implementations and
-functions that pass around a `&mut std::fmt::Formatter`. The top-level
-implementation that writes out the page body is the `impl<'a> fmt::Display for
-Item<'a>` in `html/render.rs`, which switches out to one of several `item_*`
-functions based on the kind of `Item` being rendered.
+in the `formats/` and `html/` folders, and it all starts with
+`formats::run_format`. This code is responsible for setting up a type that
+`impl FormatRenderer`, which for HTML is [`Context`].
+
+This structure contains methods that get called by `run_format` to drive the
+doc rendering, which includes:
+
+* `init` generates `static.files`, as well as search index and `src/`
+* `item` generates the item HTML files themselves
+* `after_krate` generates other global resources like `all.html`
+
+In `item`, the "page rendering" occurs, via a mixture of [Askama] templates
+and manual `write!()` calls, starting in `html/layout.rs`. The parts that have
+not been converted to templates occur within a series of `std::fmt::Display`
+implementations and functions that pass around a `&mut std::fmt::Formatter`.
+
+The parts that actually generate HTML from the items and documentation start
+with `print_item` defined in `html/render/print_item.rs`, which switches out
+to one of several `item_*` functions based on kind of `Item` being rendered.
 
 Depending on what kind of rendering code you're looking for, you'll probably
-find it either in `html/render.rs` for major items like "what sections should I
-print for a struct page" or `html/format.rs` for smaller component pieces like
-"how should I print a where clause as part of some other item".
+find it either in `html/render/mod.rs` for major items like "what sections
+should I print for a struct page" or `html/format/mod.rs` for smaller
+component pieces like "how should I print a where clause as part of some other item".
 
 Whenever rustdoc comes across an item that should print hand-written
 documentation alongside, it calls out to `html/markdown.rs` which interfaces
@@ -148,23 +180,46 @@ to us"][video])
 
 [video]: https://www.youtube.com/watch?v=hOLAGYmUQV0
 
-It's important to note that the AST cleaning can ask the compiler for
-information (crucially, `DocContext` contains a `TyCtxt`), but page rendering
-cannot. The `clean::Crate` created within `run_core` is passed outside the
-compiler context before being handed to `html::render::run`. This means that a
-lot of the "supplementary data" that isn't immediately available inside an
-item's definition, like which trait is the `Deref` trait used by the language,
-needs to be collected during cleaning, stored in the `DocContext`, and passed
-along to the `SharedContext` during HTML rendering.  This manifests as a bunch
-of shared state, context variables, and `RefCell`s.
-
-Also of note is that some items that come from "asking the compiler" don't go
-directly into the `DocContext` - for example, when loading items from a foreign
-crate, rustdoc will ask about trait implementations and generate new `Item`s
-for the impls based on that information. This goes directly into the returned
-`Crate` rather than roundabout through the `DocContext`. This way, these
-implementations can be collected alongside the others, right before rendering
-the HTML.
+It's important to note that rustdoc can ask the compiler for type information
+directly, even during HTML generation. This [didn't used to be the case], and
+a lot of rustdoc's architecture was designed around not doing that, but a
+`TyCtxt` is now passed to `formats::renderer::run_format`, which is used to
+run generation for both HTML and the
+(unstable as of <!-- date-check --> March 2023) JSON format.
+
+[didn't used to be the case]: https://github.com/rust-lang/rust/pull/80090
+
+This change has allowed other changes to remove data from the "clean" AST
+that can be easily derived from `TyCtxt` queries, and we'll usually accept
+PRs that remove fields from "clean" (it's been soft-deprecated), but this
+is complicated from two other constraints that rustdoc runs under:
+
+* Docs can be generated for crates that don't actually pass type checking.
+  This is used for generating docs that cover mutually-exclusive platform
+  configurations, such as `libstd` having a single package of docs that
+  cover all supported operating systems. This means rustdoc has to be able
+  to generate docs from HIR.
+* Docs can inline across crates. Since crate metadata doesn't contain HIR,
+  it must be possible to generate inlined docs from the `rustc_middle` data.
+
+The "clean" AST acts as a common output format for both input formats. There
+is also some data in clean that doesn't correspond directly to HIR, such as
+synthetic `impl`s for auto traits and blanket `impl`s generated by the
+`collect-trait-impls` pass.
+
+Some additional data is stored in
+`html::render::context::{Context, SharedContext}`. These two types serve as
+ways to segregate rustdoc's data for an eventual future with multithreaded doc
+generation, as well as just keeping things organized:
+
+* [`Context`] stores data used for generating the current page, such as its
+  path, a list of HTML IDs that have been used (to avoid duplicate `id=""`),
+  and the pointer to `SharedContext`.
+* [`SharedContext`] stores data that does not vary by page, such as the `tcx`
+  pointer, and a list of all types.
+
+[`Context`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustdoc/html/render/context/struct.Context.html
+[`SharedContext`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustdoc/html/render/context/struct.SharedContext.html
 
 ## Other tricks up its sleeve
 
diff --git a/src/doc/rustc-dev-guide/src/rustdoc.md b/src/doc/rustc-dev-guide/src/rustdoc.md
index d58b27bb7..cbe5e8b1f 100644
--- a/src/doc/rustc-dev-guide/src/rustdoc.md
+++ b/src/doc/rustc-dev-guide/src/rustdoc.md
@@ -1,8 +1,5 @@
 # Rustdoc overview
 
-`rustdoc` uses `rustc` internals (and, of course, the standard library), so you
-will have to build the compiler and `std` once before you can build `rustdoc`.
-
 `rustdoc` lives in-tree with the
 compiler and standard library. This chapter is about how it works.
 For information about Rustdoc's features and how to use them, see
@@ -12,6 +9,11 @@ For more details about how rustdoc works, see the
 
 [Rustdoc internals]: ./rustdoc-internals.md
 
+<!-- toc -->
+
+`rustdoc` uses `rustc` internals (and, of course, the standard library), so you
+will have to build the compiler and `std` once before you can build `rustdoc`.
+
 Rustdoc is implemented entirely within the crate [`librustdoc`][rd]. It runs
 the compiler up to the point where we have an internal representation of a
 crate (HIR) and the ability to run some queries about the types of items. [HIR]
diff --git a/src/doc/rustc-dev-guide/src/tests/compiletest.md b/src/doc/rustc-dev-guide/src/tests/compiletest.md
index 5fc6ba809..f066992dc 100644
--- a/src/doc/rustc-dev-guide/src/tests/compiletest.md
+++ b/src/doc/rustc-dev-guide/src/tests/compiletest.md
@@ -11,6 +11,16 @@ efficient test execution (parallel execution is supported),
 and allows the test author to configure behavior and expected results of both
 individual and groups of tests.
 
+> NOTE:
+> For macOS users, `SIP` (System Integrity Protection) [may consistently
+> check the compiled binary by sending network requests to Apple][zulip],
+> so you may get a huge performance degradation when running tests.
+>
+> You can resolve it by tweaking the following settings:
+> `Privacy & Security -> Developer Tools -> Add Terminal (Or VsCode, etc.)`.
+
+[zulip]: https://rust-lang.zulipchat.com/#narrow/stream/182449-t-compiler.2Fhelp/topic/.E2.9C.94.20Is.20there.20any.20performance.20issue.20for.20MacOS.3F
+
 `compiletest` may check test code for success, for runtime failure,
 or for compile-time failure.
 Tests are typically organized as a Rust source file with annotations in
diff --git a/src/doc/rustc-dev-guide/src/the-parser.md b/src/doc/rustc-dev-guide/src/the-parser.md
index 0d37704e8..f0436350a 100644
--- a/src/doc/rustc-dev-guide/src/the-parser.md
+++ b/src/doc/rustc-dev-guide/src/the-parser.md
@@ -1,8 +1,5 @@
 # Lexing and Parsing
 
-As of <!-- date-check --> January 2021, the lexer and parser are undergoing
-refactoring to allow extracting them into libraries.
-
 The very first thing the compiler does is take the program (in Unicode
 characters) and turn it into something the compiler can work with more
 conveniently than strings. This happens in two stages: Lexing and Parsing.
diff --git a/src/doc/rustc-dev-guide/src/tracing.md b/src/doc/rustc-dev-guide/src/tracing.md
index 0bba73f74..af484ab5f 100644
--- a/src/doc/rustc-dev-guide/src/tracing.md
+++ b/src/doc/rustc-dev-guide/src/tracing.md
@@ -144,6 +144,9 @@ $ RUSTC_LOG=debug rustc +stage1 my-file.rs 2>all-log
 # compilers.
 $ RUSTC_LOG=rustc_codegen_ssa=info rustc +stage1 my-file.rs
 
+# This will show all logs in `rustc_codegen_ssa` and `rustc_resolve`.
+$ RUSTC_LOG=rustc_codegen_ssa,rustc_resolve rustc +stage1 my-file.rs
+
 # This will show the output of all `info!` calls made by rustdoc
 # or any rustc library it calls.
 $ RUSTDOC_LOG=info rustdoc +stage1 my-file.rs
diff --git a/src/doc/rustc-dev-guide/src/type-inference.md b/src/doc/rustc-dev-guide/src/type-inference.md
index 2bafeb247..4043789d0 100644
--- a/src/doc/rustc-dev-guide/src/type-inference.md
+++ b/src/doc/rustc-dev-guide/src/type-inference.md
@@ -68,7 +68,7 @@ inference works, or perhaps this blog post on
 [Unification in the Chalk project]: http://smallcultfollowing.com/babysteps/blog/2017/03/25/unification-in-chalk-part-1/
 
 All told, the inference context stores five kinds of inference variables
-(as of <!-- date-check --> June 2021):
+(as of <!-- date-check --> March 2023):
 
 - Type variables, which come in three varieties:
   - General type variables (the most common). These can be unified with any