Auto merge of #135127 - Kobzol:rustc-dev-guide-sync, r=BoxyUwU

rustc-dev-guide subtree update

This PR performs the first update of rustc-dev-guide code from its repository.

r? `@BoxyUwU`

Author: bors

src/doc/rustc-dev-guide/README.md

@@ -70,46 +70,21 @@ $ ENABLE_LINKCHECK=1 mdbook serve
 We use `mdbook-toc` to auto-generate TOCs for long sections. You can invoke the preprocessor by
 including the `<!-- toc -->` marker at the place where you want the TOC.
 
-## How to fix toolstate failures
-
-> [!NOTE]
-> Currently, we do not track the rustc-dev-guide toolstate due to
-> [spurious failures](https://github.com/rust-lang/rust/pull/71731),
-> but we leave these instructions for when we do it again in the future.
-
-1. You will get a ping from the toolstate commit. e.g. https://github.com/rust-lang-nursery/rust-toolstate/commit/8ffa0e4c30ac9ba8546b7046e5c4ccc2b96ebdd4
-
-2. The commit contains a link to the PR that caused the breakage. e.g. https://github.com/rust-lang/rust/pull/64321
-
-3. If you go to that PR's thread, there is a post from bors with a link to the CI status: https://github.com/rust-lang/rust/pull/64321#issuecomment-529763807
-
-4. Follow the check-actions link to get to the Actions page for that build
-
-5. There will be approximately 1 billion different jobs for the build. They are for different configurations and platforms. The rustc-dev-guide build only runs on the Linux x86_64-gnu-tools job. So click on that job in the list, which is about 60% down in the list.
-
-6. Click the Run build step in the job to get the console log for the step.
-
-7. Click on the log and Ctrl-f to get a search box in the log
-
-8. Search for rustc-dev-guide. This gets you to the place where the links are checked. It is usually ~11K lines into the log.
-
-9. Look at the links in the log near that point in the log
-
-10. Fix those links in the rustc-dev-guide (by making a PR in the rustc-dev-guide repo)
-
-11. Make a PR on the rust-lang/rust repo to update the rustc-dev-guide git submodule in src/docs/rustc-dev-guide.
-To make a PR, the following steps are useful.
-
-```bash
-# Assuming you already cloned the rust-lang/rust repo and you're in the correct directory
-git submodule update --remote src/doc/rustc-dev-guide
-git add -u
-git commit -m "Update rustc-dev-guide"
-# Note that you can use -i, which is short for --incremental, in the following command
-./x test --incremental src/doc/rustc-dev-guide # This is optional and should succeed anyway
-# Open a PR in rust-lang/rust
-```
-
-12. Wait for PR to merge
-
-Voilà!
+## Synchronizing josh subtree with rustc
+
+This repository is linked to `rust-lang/rust` as a [josh](https://josh-project.github.io/josh/intro.html) subtree. You can use the following commands to synchronize the subtree in both directions.
+
+### Pull changes from `rust-lang/rust` into this repository
+1) Checkout a new branch that will be used to create a PR into `rust-lang/rustc-dev-guide`
+2) Run the pull command
+    ```
+    $ cargo run --manifest-path josh-sync/Cargo.toml rustc-pull
+    ```
+3) Push the branch to your fork and create a PR into `rustc-dev-guide`
+
+### Push changes from this repository into `rust-lang/rust`
+1) Run the push command to create a branch named `<branch-name>` in a `rustc` fork under the `<gh-username>` account
+    ```
+    $ cargo run --manifest-path josh-sync/Cargo.toml rustc-push <branch-name> <gh-username>
+    ```
+2) Create a PR from `<branch-name>` into `rust-lang/rust`

src/doc/rustc-dev-guide/josh-sync/Cargo.lock

@@ -0,0 +1,10 @@
+[package]
+name = "josh-sync"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+anyhow = "1.0.95"
+clap = { version = "4.5.21", features = ["derive"] }
+directories = "5"
+xshell = "0.2.6"

src/doc/rustc-dev-guide/josh-sync/Cargo.toml

@@ -0,0 +1,4 @@
+# Git josh sync
+This utility serves for syncing the josh git subtree to and from the rust-lang/rust repository.
+
+See CLI help for usage.

src/doc/rustc-dev-guide/josh-sync/README.md

@@ -0,0 +1,32 @@
+use clap::Parser;
+use crate::sync::GitSync;
+
+mod sync;
+
+#[derive(clap::Parser)]
+enum Args {
+    /// Pull changes from the main `rustc` repository.
+    /// This creates new commits that should be then merged into `rustc-dev-guide`.
+    RustcPull,
+    /// Push changes from `rustc-dev-guide` to the given `branch` of a `rustc` fork under the given
+    /// GitHub `username`.
+    /// The pushed branch should then be merged into the `rustc` repository.
+    RustcPush {
+        branch: String,
+        github_username: String
+    }
+}
+
+fn main() -> anyhow::Result<()> {
+    let args = Args::parse();
+    let sync = GitSync::from_current_dir()?;
+    match args {
+        Args::RustcPull => {
+            sync.rustc_pull(None)?;
+        }
+        Args::RustcPush { github_username, branch } => {
+            sync.rustc_push(github_username, branch)?;
+        }
+    }
+    Ok(())
+}

src/doc/rustc-dev-guide/josh-sync/src/main.rs

@@ -0,0 +1,234 @@
+use std::ops::Not;
+use std::path::PathBuf;
+use std::{env, net, process};
+use std::io::Write;
+use std::time::Duration;
+use anyhow::{anyhow, bail, Context};
+use xshell::{cmd, Shell};
+
+/// Used for rustc syncs.
+const JOSH_FILTER: &str = ":/src/doc/rustc-dev-guide";
+const JOSH_PORT: u16 = 42042;
+const UPSTREAM_REPO: &str = "rust-lang/rust";
+
+pub struct GitSync {
+    dir: PathBuf,
+}
+
+/// This code was adapted from the miri repository
+/// (https://github.com/rust-lang/miri/blob/6a68a79f38064c3bc30617cca4bdbfb2c336b140/miri-script/src/commands.rs#L236).
+impl GitSync {
+    pub fn from_current_dir() -> anyhow::Result<Self> {
+        Ok(Self {
+            dir: std::env::current_dir()?
+        })
+    }
+
+    pub fn rustc_pull(&self, commit: Option<String>) -> anyhow::Result<()> {
+        let sh = Shell::new()?;
+        sh.change_dir(&self.dir);
+        let commit = commit.map(Ok).unwrap_or_else(|| {
+            let rust_repo_head =
+                cmd!(sh, "git ls-remote https://github.com/{UPSTREAM_REPO}/ HEAD").read()?;
+            rust_repo_head
+                .split_whitespace()
+                .next()
+                .map(|front| front.trim().to_owned())
+                .ok_or_else(|| anyhow!("Could not obtain Rust repo HEAD from remote."))
+        })?;
+        // Make sure the repo is clean.
+        if cmd!(sh, "git status --untracked-files=no --porcelain").read()?.is_empty().not() {
+            bail!("working directory must be clean before performing rustc pull");
+        }
+        // Make sure josh is running.
+        let josh = Self::start_josh()?;
+        let josh_url =
+            format!("http://localhost:{JOSH_PORT}/{UPSTREAM_REPO}.git@{commit}{JOSH_FILTER}.git");
+
+        // Update rust-version file. As a separate commit, since making it part of
+        // the merge has confused the heck out of josh in the past.
+        // We pass `--no-verify` to avoid running git hooks.
+        // We do this before the merge so that if there are merge conflicts, we have
+        // the right rust-version file while resolving them.
+        sh.write_file("rust-version", format!("{commit}\n"))?;
+        const PREPARING_COMMIT_MESSAGE: &str = "Preparing for merge from rustc";
+        cmd!(sh, "git commit rust-version --no-verify -m {PREPARING_COMMIT_MESSAGE}")
+            .run()
+            .context("FAILED to commit rust-version file, something went wrong")?;
+
+        // Fetch given rustc commit.
+        cmd!(sh, "git fetch {josh_url}")
+            .run()
+            .inspect_err(|_| {
+                // Try to un-do the previous `git commit`, to leave the repo in the state we found it.
+                cmd!(sh, "git reset --hard HEAD^")
+                    .run()
+                    .expect("FAILED to clean up again after failed `git fetch`, sorry for that");
+            })
+            .context("FAILED to fetch new commits, something went wrong (committing the rust-version file has been undone)")?;
+
+        // This should not add any new root commits. So count those before and after merging.
+        let num_roots = || -> anyhow::Result<u32> {
+            Ok(cmd!(sh, "git rev-list HEAD --max-parents=0 --count")
+                .read()
+                .context("failed to determine the number of root commits")?
+                .parse::<u32>()?)
+        };
+        let num_roots_before = num_roots()?;
+
+        // Merge the fetched commit.
+        const MERGE_COMMIT_MESSAGE: &str = "Merge from rustc";
+        cmd!(sh, "git merge FETCH_HEAD --no-verify --no-ff -m {MERGE_COMMIT_MESSAGE}")
+            .run()
+            .context("FAILED to merge new commits, something went wrong")?;
+
+        // Check that the number of roots did not increase.
+        if num_roots()? != num_roots_before {
+            bail!("Josh created a new root commit. This is probably not the history you want.");
+        }
+
+        drop(josh);
+        Ok(())
+    }
+
+    pub fn rustc_push(&self, github_user: String, branch: String) -> anyhow::Result<()> {
+        let sh = Shell::new()?;
+        sh.change_dir(&self.dir);
+        let base = sh.read_file("rust-version")?.trim().to_owned();
+        // Make sure the repo is clean.
+        if cmd!(sh, "git status --untracked-files=no --porcelain").read()?.is_empty().not() {
+            bail!("working directory must be clean before running `rustc-push`");
+        }
+        // Make sure josh is running.
+        let josh = Self::start_josh()?;
+        let josh_url =
+            format!("http://localhost:{JOSH_PORT}/{github_user}/rust.git{JOSH_FILTER}.git");
+
+        // Find a repo we can do our preparation in.
+        if let Ok(rustc_git) = env::var("RUSTC_GIT") {
+            // If rustc_git is `Some`, we'll use an existing fork for the branch updates.
+            sh.change_dir(rustc_git);
+        } else {
+            // Otherwise, do this in the local repo.
+            println!(
+                "This will pull a copy of the rust-lang/rust history into this checkout, growing it by about 1GB."
+            );
+            print!(
+                "To avoid that, abort now and set the `RUSTC_GIT` environment variable to an existing rustc checkout. Proceed? [y/N] "
+            );
+            std::io::stdout().flush()?;
+            let mut answer = String::new();
+            std::io::stdin().read_line(&mut answer)?;
+            if answer.trim().to_lowercase() != "y" {
+                std::process::exit(1);
+            }
+        };
+        // Prepare the branch. Pushing works much better if we use as base exactly
+        // the commit that we pulled from last time, so we use the `rust-version`
+        // file to find out which commit that would be.
+        println!("Preparing {github_user}/rust (base: {base})...");
+        if cmd!(sh, "git fetch https://github.com/{github_user}/rust {branch}")
+            .ignore_stderr()
+            .read()
+            .is_ok()
+        {
+            println!(
+                "The branch '{branch}' seems to already exist in 'https://github.com/{github_user}/rust'. Please delete it and try again."
+            );
+            std::process::exit(1);
+        }
+        cmd!(sh, "git fetch https://github.com/{UPSTREAM_REPO} {base}").run()?;
+        cmd!(sh, "git push https://github.com/{github_user}/rust {base}:refs/heads/{branch}")
+            .ignore_stdout()
+            .ignore_stderr() // silence the "create GitHub PR" message
+            .run()?;
+        println!();
+
+        // Do the actual push.
+        sh.change_dir(&self.dir);
+        println!("Pushing changes...");
+        cmd!(sh, "git push {josh_url} HEAD:{branch}").run()?;
+        println!();
+
+        // Do a round-trip check to make sure the push worked as expected.
+        cmd!(sh, "git fetch {josh_url} {branch}").ignore_stderr().read()?;
+        let head = cmd!(sh, "git rev-parse HEAD").read()?;
+        let fetch_head = cmd!(sh, "git rev-parse FETCH_HEAD").read()?;
+        if head != fetch_head {
+            bail!(
+                "Josh created a non-roundtrip push! Do NOT merge this into rustc!\n\
+                Expected {head}, got {fetch_head}."
+            );
+        }
+        println!(
+            "Confirmed that the push round-trips back to rustc-dev-guide properly. Please create a rustc PR:"
+        );
+        println!(
+            // Open PR with `subtree update` title to silence the `no-merges` triagebot check
+            "    https://github.com/{UPSTREAM_REPO}/compare/{github_user}:{branch}?quick_pull=1&title=Rustc+dev+guide+subtree+update&body=r?+@ghost"
+        );
+
+        drop(josh);
+        Ok(())
+    }
+
+    fn start_josh() -> anyhow::Result<impl Drop> {
+        // Determine cache directory.
+        let local_dir = {
+            let user_dirs =
+                directories::ProjectDirs::from("org", "rust-lang", "rustc-dev-guide-josh").unwrap();
+            user_dirs.cache_dir().to_owned()
+        };
+
+        // Start josh, silencing its output.
+        let mut cmd = process::Command::new("josh-proxy");
+        cmd.arg("--local").arg(local_dir);
+        cmd.arg("--remote").arg("https://github.com");
+        cmd.arg("--port").arg(JOSH_PORT.to_string());
+        cmd.arg("--no-background");
+        cmd.stdout(process::Stdio::null());
+        cmd.stderr(process::Stdio::null());
+        let josh = cmd.spawn().context("failed to start josh-proxy, make sure it is installed")?;
+
+        // Create a wrapper that stops it on drop.
+        struct Josh(process::Child);
+        impl Drop for Josh {
+            fn drop(&mut self) {
+                #[cfg(unix)]
+                {
+                    // Try to gracefully shut it down.
+                    process::Command::new("kill")
+                        .args(["-s", "INT", &self.0.id().to_string()])
+                        .output()
+                        .expect("failed to SIGINT josh-proxy");
+                    // Sadly there is no "wait with timeout"... so we just give it some time to finish.
+                    std::thread::sleep(Duration::from_millis(100));
+                    // Now hopefully it is gone.
+                    if self.0.try_wait().expect("failed to wait for josh-proxy").is_some() {
+                        return;
+                    }
+                }
+                // If that didn't work (or we're not on Unix), kill it hard.
+                eprintln!(
+                    "I have to kill josh-proxy the hard way, let's hope this does not break anything."
+                );
+                self.0.kill().expect("failed to SIGKILL josh-proxy");
+            }
+        }
+
+        // Wait until the port is open. We try every 10ms until 1s passed.
+        for _ in 0..100 {
+            // This will generally fail immediately when the port is still closed.
+            let josh_ready = net::TcpStream::connect_timeout(
+                &net::SocketAddr::from(([127, 0, 0, 1], JOSH_PORT)),
+                Duration::from_millis(1),
+            );
+            if josh_ready.is_ok() {
+                return Ok(Josh(josh));
+            }
+            // Not ready yet.
+            std::thread::sleep(Duration::from_millis(10));
+        }
+        bail!("Even after waiting for 1s, josh-proxy is still not available.")
+    }
+}

src/doc/rustc-dev-guide/josh-sync/src/sync.rs

@@ -0,0 +1 @@
+dcfa38fe234de9304169afc6638e81d0dd222c06

src/doc/rustc-dev-guide/rust-version

@@ -134,14 +134,13 @@
 
 - [Prologue](./part-4-intro.md)
 - [Generic parameter definitions](./generic_parameters_summary.md)
-    - [Implementation nuances of early/late bound parameters](./early-late-bound-params/early-late-bound-implementation-nuances.md)
-    - [Interactions with turbofishing](./early-late-bound-params/turbofishing-and-early-late-bound.md)
+    - [`EarlyBinder` and instantiating parameters](./ty_module/early_binder.md)
+- [Binders and Higher ranked regions](./ty_module/binders.md)
+    - [Instantiating binders](./ty_module/instantiating_binders.md)
+- [Early vs Late bound parameters](./early_late_parameters.md)
 - [The `ty` module: representing types](./ty.md)
     - [ADTs and Generic Arguments](./ty_module/generic_arguments.md)
     - [Parameter types/consts/regions](./ty_module/param_ty_const_regions.md)
-    - [`EarlyBinder` and instantiating parameters](./ty_module/early_binder.md)
-    - [`Binder` and Higher ranked regions](./ty_module/binders.md)
-    - [Instantiating binders](./ty_module/instantiating_binders.md)
 - [`TypeFolder` and `TypeFoldable`](./ty-fold.md)
 - [Parameter Environments](./param_env/param_env_summary.md)
     - [What is it?](./param_env/param_env_what_is_it.md)

src/doc/rustc-dev-guide/src/SUMMARY.md

@@ -3,24 +3,24 @@
 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`)
+2. As a git (e.g. `clippy`) or a [josh] (e.g. `miri`) subtree
 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.
+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
+- Use submodules for tools that are independent of the compiler
 
-## External Dependencies (subtree)
+## External Dependencies (subtrees)
 
-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:
+The following external projects are managed using some form of a `subtree`:
 
-* [Clippy](https://github.com/rust-lang/rust-clippy)
-* [Miri]
+* [clippy](https://github.com/rust-lang/rust-clippy)
+* [miri](https://github.com/rust-lang/miri)
 * [rustfmt](https://github.com/rust-lang/rustfmt)
 * [rust-analyzer](https://github.com/rust-lang/rust-analyzer)
-
-[Miri]: https://github.com/rust-lang/miri
+* [rustc_codegen_cranelift](https://github.com/rust-lang/rustc_codegen_cranelift)
 
 In contrast to `submodule` dependencies
 (see below for those), the `subtree` dependencies are just regular files and directories which can
@@ -29,6 +29,20 @@ 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.
 
+`subtree` dependencies are currently managed by two distinct approaches:
+
+* Using `git subtree`
+  * `clippy` ([sync guide](https://doc.rust-lang.org/nightly/clippy/development/infrastructure/sync.html#performing-the-sync-from-rust-langrust-to-clippy))
+  * `rustfmt`
+  * `rustc_codegen_cranelift` ([sync script](https://github.com/rust-lang/rustc_codegen_cranelift/blob/113af154d459e41b3dc2c5d7d878e3d3a8f33c69/scripts/rustup.sh#L7))
+* Using the [josh] tool
+  * `miri` ([sync guide](https://github.com/rust-lang/miri/blob/master/CONTRIBUTING.md#advanced-topic-syncing-with-the-rustc-repo))
+  * `rust-analyzer` ([sync script](https://github.com/rust-lang/rust-analyzer/blob/2e13684be123eca7181aa48e043e185d8044a84a/xtask/src/release.rs#L147))
+
+The [josh] tool is an alternative to git subtrees, which manages git history in a different way and scales better to larger repositories. Specific tooling is required to work with josh, you can check out the `miri` or `rust-analyzer` scripts linked above for inspiration. If you want to migrate a subtree from `git subtree` to josh, you can check out [this guide](https://hackmd.io/7pOuxnkdQDaL1Y1FQr65xg).
+
+Below you can find a guide on how to perform push and pull synchronization with the main rustc repo using `git subtree`, although these instructions might differ repo from repo.
+
 ### Synchronizing a subtree
 
 Periodically the changes made to subtree based dependencies need to be synchronized between this
@@ -84,7 +98,6 @@ 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
@@ -111,3 +124,4 @@ the week leading up to the beta cut.
 [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
+[josh]: https://josh-project.github.io/josh/intro.html

src/doc/rustc-dev-guide/src/early-late-bound-params/early-late-bound-implementation-nuances.md

@@ -25,42 +25,4 @@ Interestingly, `ty::Generics` does not currently contain _every_ generic paramet
 [ch_representing_types]: ./ty.md
 [`ty::Generics`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/struct.Generics.html
 [`GenericParamDef`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/generics/struct.GenericParamDef.html
-
-# Early vs Late bound parameters
-
-
-```rust
-fn foo<'a, T>(b: &'a T) -> &'a T { b }
-//     ^^  ^early bound
-//     ^^
-//     ^^late bound
-```
-
-Generally when referring to an item with generic parameters you must specify a list of generic arguments corresponding to the item's generic parameters. In some cases it is permitted to elide these arguments but still, implicitly, a set of arguments are provided (e.g. `Vec::default()` desugars to `Vec::<_>::default()`).
-
-For functions this is not necessarily the case, for example if we take the function `foo` from the example above and write the following code:
-```rust
-fn main() {
-    let f = foo::<_>;
-
-    let b = String::new();
-    let c = String::new();
-    
-    f(&b);
-    drop(b);
-    f(&c);
-}
-```
-
-This code compiles perfectly fine even though there is no single lifetime that could possibly be specified in `foo::<_>` that would allow for both
-the `&b` and `&c` borrows to be used as arguments (note: the `drop(b)` line forces the `&b` borrow to be shorter than the `&c` borrow). This works because the `'a` lifetime is _late bound_.
-
-A generic parameter being late bound means that when we write `foo::<_>` we do not actually provide an argument for that parameter, instead we wait until _calling_ the function to provide the generic argument. In the above example this means that we are doing something like `f::<'_>(&b);` and `f::<'_>(&c);` (although in practice we do not actually support turbofishing late bound parameters in this manner)
-
-It may be helpful to think of "early bound parameter" or "late bound parameter" as meaning "early provided parameter" and "late provided parameter", i.e. we provide the argument to the parameter either early (when naming the function) or late (when calling it).
-
-Late bound parameters on functions are tracked with a [`Binder`] when accessing the signature of the function, this can be done with the [`fn_sig`] query. For more information of binders see the [chapter on `Binder`s ][ch_binders].
-
-[`Binder`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_type_ir/binder/struct.Binder.html
-[`fn_sig`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/context/struct.TyCtxt.html#method.fn_sig
-[ch_binders]: ./ty_module/binders.md
+[ch_binders]: ./ty_module/binders.md

src/doc/rustc-dev-guide/src/early-late-bound-params/turbofishing-and-early-late-bound.md

@@ -67,6 +67,7 @@ imported to use an inherent method, they are associated with the type
 itself (note that inherent impls can only be defined in the same
 crate as the type itself).
 
+<!--
 FIXME: Inherent candidates are not always derived from impls.  If you
 have a trait object, such as a value of type `Box<ToString>`, then the
 trait methods (`to_string()`, in this case) are inherently associated
@@ -76,7 +77,8 @@ to change: when DST's "impl Trait for Trait" is complete, trait object
 dispatch could be subsumed into trait matching, and the type parameter
 behavior should be reconsidered in light of where clauses.
 
-TODO: Is this FIXME still accurate?
+Is this still accurate?
+-->
 
 **Extension candidates** are derived from imported traits.  If I have
 the trait `ToString` imported, and I call `to_string()` as a method,

src/doc/rustc-dev-guide/src/early_late_parameters.md

@@ -1,5 +1,7 @@
 # Normalization in the new solver
 
+> FIXME: Normalization has been changed significantly since this chapter was written.
+
 With the new solver we've made some fairly significant changes to normalization when compared
 to the existing implementation.
 
@@ -52,12 +54,14 @@ before assigning the resulting rigid type to an inference variable. This is used
 This has to be used whenever we match on the value of some type, both inside
 and outside of the trait solver.
 
+<!--
 FIXME: structure, maybe we should have an "alias handling" chapter instead as
 talking about normalization without explaining that doesn't make too much
 sense.
 
 FIXME: it is likely that this will subtly change again by mostly moving structural
 normalization into `NormalizesTo`.
+-->
 
 [structural_norm]: https://github.com/rust-lang/rust/blob/2627e9f3012a97d3136b3e11bf6bd0853c38a534/compiler/rustc_trait_selection/src/solve/alias_relate.rs#L140-L175
 [structural-relate]: https://github.com/rust-lang/rust/blob/a0569fa8f91b5271e92d2f73fd252de7d3d05b9c/compiler/rustc_trait_selection/src/solve/alias_relate.rs#L88-L107
@@ -72,11 +76,13 @@ possible. However, this only works for aliases referencing bound variables if th
 not ambiguous as we're unable to replace the alias with a corresponding inference
 variable without leaking universes.
 
+<!--
 FIXME: we previously had to also be careful about instantiating the new inference
 variable with another normalizeable alias. Due to our recent changes to generalization,
 this should not be the case anymore. Equating an inference variable with an alias
 now always uses `AliasRelate` to fully normalize the alias before instantiating the
 inference variable: [source][generalize-no-alias]
+-->
 
 [generalize-no-alias]: https://github.com/rust-lang/rust/blob/a0569fa8f91b5271e92d2f73fd252de7d3d05b9c/compiler/rustc_infer/src/infer/relate/generalize.rs#L353-L358
 

src/doc/rustc-dev-guide/src/external-repos.md

@@ -60,6 +60,7 @@ Finally, we check whether the item bounds of the opaque hold for the expected ty
 [eq-prev]: https://github.com/rust-lang/rust/blob/384d26fc7e3bdd7687cc17b2662b091f6017ec2a/compiler/rustc_trait_selection/src/solve/normalizes_to/opaque_types.rs#L51-L59
 [insert-storage]: https://github.com/rust-lang/rust/blob/384d26fc7e3bdd7687cc17b2662b091f6017ec2a/compiler/rustc_trait_selection/src/solve/normalizes_to/opaque_types.rs#L68
 [item-bounds-ck]: https://github.com/rust-lang/rust/blob/384d26fc7e3bdd7687cc17b2662b091f6017ec2a/compiler/rustc_trait_selection/src/solve/normalizes_to/opaque_types.rs#L69-L74
+
 [^1]: FIXME: this should ideally only result in a unique candidate given that we require the args to be placeholders and regions are always inference vars
 [^2]: FIXME: why do we check whether the expected type is rigid for this.
 
@@ -101,6 +102,7 @@ The handling of member constraints does not change in the new solver. See the
 
 FIXME: We need to continue to support calling methods on still unconstrained
 opaque types in their defining scope. It's unclear how to best do this.
+
 ```rust
 use std::future::Future;
 use futures::FutureExt;

src/doc/rustc-dev-guide/src/generic_parameters_summary.md

@@ -441,6 +441,46 @@ $ COMPILETEST_FORCE_STAGE0=1 x test --stage 0 tests/run-make/<test-name>
 
 Of course, some tests will not successfully *run* in this way.
 
+#### Using rust-analyzer with `rmake.rs`
+
+Like other test programs, the `rmake.rs` scripts used by run-make tests do not
+have rust-analyzer integration by default.
+
+To work around this when working on a particular test, temporarily create a
+`Cargo.toml` file in the test's directory
+(e.g. `tests/run-make/sysroot-crates-are-unstable/Cargo.toml`)
+with these contents:
+
+<div class="warning">
+Be careful not to add this `Cargo.toml` or its `Cargo.lock` to your actual PR!
+</div>
+
+```toml
+# Convince cargo that this isn't part of an enclosing workspace.
+[workspace]
+
+[package]
+name = "rmake"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+run_make_support = { path = "../../../src/tools/run-make-support" }
+
+[[bin]]
+name = "rmake"
+path = "rmake.rs"
+```
+
+Then add a corresponding entry to `"rust-analyzer.linkedProjects"`
+(e.g. in `.vscode/settings.json`):
+
+```json
+"rust-analyzer.linkedProjects": [
+  "tests/run-make/sysroot-crates-are-unstable/Cargo.toml"
+],
+```
+
 #### Using Makefiles (legacy)
 
 <div class="warning">

src/doc/rustc-dev-guide/src/method-lookup.md

@@ -2,7 +2,9 @@
 
 <!-- toc -->
 
-> **FIXME(jieyouxu)** completely revise this chapter.
+<!--
+FIXME(jieyouxu) completely revise this chapter.
+-->
 
 Directives are special comments that tell compiletest how to build and interpret
 a test. They must appear before the Rust source in the test. They may also
@@ -248,10 +250,11 @@ Consider writing the test as a proper incremental test instead.
 |-------------|--------------------------------------------------------------|------------------------------------------|---------------------------|
 | `doc-flags` | Flags passed to `rustdoc` when building the test or aux file | `rustdoc`, `js-doc-test`, `rustdoc-json` | Any valid `rustdoc` flags |
 
-> **FIXME(rustdoc)**: what does `check-test-line-numbers-match` do?
->
-> Asked in
-> <https://rust-lang.zulipchat.com/#narrow/stream/266220-t-rustdoc/topic/What.20is.20the.20.60check-test-line-numbers-match.60.20directive.3F>.
+<!--
+**FIXME(rustdoc)**: what does `check-test-line-numbers-match` do?
+Asked in
+<https://rust-lang.zulipchat.com/#narrow/stream/266220-t-rustdoc/topic/What.20is.20the.20.60check-test-line-numbers-match.60.20directive.3F>.
+-->
 
 ### Pretty printing
 

src/doc/rustc-dev-guide/src/solve/normalization.md

@@ -10,7 +10,7 @@ stream and say hello!
 [Types team]: https://github.com/rust-lang/types-team
 [`#t-types`]: https://rust-lang.zulipchat.com/#narrow/stream/144729-t-types
 
-The new-style trait solver is based on the work done in [chalk][chalk]. Chalk
+The new-style trait solver is based on the work done in [chalk]. Chalk
 recasts Rust's trait system explicitly in terms of logic programming. It does
 this by "lowering" Rust code into a kind of logic program we can then execute
 queries against.
@@ -30,7 +30,7 @@ You can read more about chalk itself in the
 ## Ongoing work
 The design of the new-style trait solving happens in two places:
 
-**chalk**. The [chalk][chalk] repository is where we experiment with new ideas
+**chalk**. The [chalk] repository is where we experiment with new ideas
 and designs for the trait system.
 
 **rustc**. Once we are happy with the logical rules, we proceed to

src/doc/rustc-dev-guide/src/solve/opaque-types.md

@@ -47,10 +47,10 @@ fn bar(foo: Foo<u32, f32>) {
 
 In the compiler the `instantiate` call for this is done in [`FieldDef::ty`] ([src][field_def_ty_src]), at some point during type checking `bar` we will wind up calling `FieldDef::ty(x, &[u32, f32])` in order to obtain the type of `foo.x`.
 
-**Note on indices:** It is possible for the indices in `Param` to not match with what the `EarlyBinder` binds. For
-example, the index could be out of bounds or it could be the index of a lifetime when we were expecting a type.
-These sorts of errors would be caught earlier in the compiler when translating from a `rustc_hir::Ty` to a `ty::Ty`.
-If they occur later, that is a compiler bug.
+**Note on indices:** It is a bug if the index of a `Param` does not match what the `EarlyBinder` binds. For
+example, if the index is out of bounds or the index index of a lifetime corresponds to a type parameter.
+These sorts of errors are caught earlier in the compiler during name resolution where we disallow references
+to generics parameters introduced by items that should not be nameable by the inner item. 
 
 [`FieldDef::ty`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/struct.FieldDef.html#method.ty
 [field_def_ty_src]: https://github.com/rust-lang/rust/blob/44d679b9021f03a79133021b94e6d23e9b55b3ab/compiler/rustc_middle/src/ty/mod.rs#L1421-L1426