rustc-dev-guide subtree update

src/doc/rustc-dev-guide/.github/workflows/ci.yml

@@ -14,7 +14,7 @@ jobs:
     if: github.repository == 'rust-lang/rustc-dev-guide'
     runs-on: ubuntu-latest
     env:
-      MDBOOK_VERSION: 0.4.21
+      MDBOOK_VERSION: 0.4.48
       MDBOOK_LINKCHECK2_VERSION: 0.9.1
       MDBOOK_MERMAID_VERSION: 0.12.6
       MDBOOK_TOC_VERSION: 0.11.2

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

@@ -194,7 +194,7 @@ impl GitSync {
         );
         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"
+            "    https://github.com/{UPSTREAM_REPO}/compare/{github_user}:{branch}?quick_pull=1&title=rustc-dev-guide+subtree+update&body=r?+@ghost"
         );
 
         drop(josh);

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

@@ -1 +1 @@
-deb947971c8748f5c6203548ce4af9022f21eaf0
+0c33fe2c3d3eecadd17a84b110bb067288a64f1c

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

@@ -157,6 +157,7 @@
     - [ADTs and Generic Arguments](./ty_module/generic_arguments.md)
     - [Parameter types/consts/regions](./ty_module/param_ty_const_regions.md)
 - [`TypeFolder` and `TypeFoldable`](./ty-fold.md)
+- [Aliases and Normalization](./normalization.md)
 - [Typing/Param Envs](./typing_parameter_envs.md)
 - [Type inference](./type-inference.md)
 - [Trait solving](./traits/resolution.md)
@@ -176,7 +177,6 @@
         - [Coinduction](./solve/coinduction.md)
         - [Caching](./solve/caching.md)
         - [Proof trees](./solve/proof-trees.md)
-        - [Normalization](./solve/normalization.md)
         - [Opaque types](./solve/opaque-types.md)
         - [Significant changes and quirks](./solve/significant-changes.md)
     - [`Unsize` and `CoerceUnsized` traits](./traits/unsize.md)

src/doc/rustc-dev-guide/src/building/bootstrapping/intro.md

@@ -6,8 +6,8 @@ of the same compiler.
 
 This raises a chicken-and-egg paradox: where did the first compiler come from?
 It must have been written in a different language. In Rust's case it was
-[written in OCaml][ocaml-compiler]. However it was abandoned long ago and the
-only way to build a modern version of rustc is a slightly less modern
+[written in OCaml][ocaml-compiler]. However, it was abandoned long ago, and the
+only way to build a modern version of rustc is with a slightly less modern
 version.
 
 This is exactly how `x.py` works: it downloads the current beta release of

src/doc/rustc-dev-guide/src/building/bootstrapping/what-bootstrapping-does.md

@@ -8,8 +8,8 @@ the same compiler.
 
 This raises a chicken-and-egg paradox: where did the first compiler come from?
 It must have been written in a different language. In Rust's case it was
-[written in OCaml][ocaml-compiler]. However it was abandoned long ago and the
-only way to build a modern version of `rustc` is a slightly less modern version.
+[written in OCaml][ocaml-compiler]. However, it was abandoned long ago, and the
+only way to build a modern version of `rustc` is with a slightly less modern version.
 
 This is exactly how [`./x.py`] works: it downloads the current beta release of
 `rustc`, then uses it to compile the new compiler.

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

@@ -62,21 +62,20 @@ huge. There is also the `rustc` crate which is the actual binary (i.e. the
 [`rustc_driver`] crate, which drives the various parts of compilation in other
 crates.
 
-The dependency structure of these crates is complex, but roughly it is
+The dependency order of these crates is complex, but roughly it is
 something like this:
 
-- `rustc` (the binary) calls [`rustc_driver::main`][main].
-    - [`rustc_driver`] depends on a lot of other crates, but the main one is
-      [`rustc_interface`].
-        - [`rustc_interface`] depends on most of the other compiler crates. It
-          is a fairly generic interface for driving the whole compilation.
-            - Most of the other `rustc_*` crates depend on [`rustc_middle`],
-              which defines a lot of central data structures in the compiler.
-                - [`rustc_middle`] and most of the other crates depend on a
-                  handful of crates representing the early parts of the
-                  compiler (e.g. the parser), fundamental data structures (e.g.
-                  [`Span`]), or error reporting: [`rustc_data_structures`],
-                  [`rustc_span`], [`rustc_errors`], etc.
+1. `rustc` (the binary) calls [`rustc_driver::main`][main].
+1. [`rustc_driver`] depends on a lot of other crates, but the main one is
+   [`rustc_interface`].
+1. [`rustc_interface`] depends on most of the other compiler crates. It is a
+   fairly generic interface for driving the whole compilation.
+1. Most of the other `rustc_*` crates depend on [`rustc_middle`], which defines
+   a lot of central data structures in the compiler.
+1. [`rustc_middle`] and most of the other crates depend on a handful of crates
+   representing the early parts of the compiler (e.g. the parser), fundamental
+   data structures (e.g. [`Span`]), or error reporting:
+   [`rustc_data_structures`], [`rustc_span`], [`rustc_errors`], etc.
 
 [`rustc_data_structures`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_data_structures/index.html
 [`rustc_driver`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_driver/index.html
@@ -87,8 +86,12 @@ something like this:
 [`Span`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_span/struct.Span.html
 [main]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_driver/fn.main.html
 
-You can see the exact dependencies by reading the [`Cargo.toml`] for the various
-crates, just like a normal Rust crate.
+You can see the exact dependencies by running `cargo tree`,
+just like you would for any other Rust package:
+
+```console
+cargo tree --package rustc_driver
+```
 
 One final thing: [`src/llvm-project`] is a submodule for our fork of LLVM.
 During bootstrapping, LLVM is built and the [`compiler/rustc_llvm`] crate

src/doc/rustc-dev-guide/src/guides/editions.md

@@ -193,6 +193,23 @@ When a user runs `cargo fix --edition`, cargo will pass the `--force-warn rust-2
 flag to force all of these lints to appear during the edition migration.
 Cargo also passes `--cap-lints=allow` so that no other lints interfere with the edition migration.
 
+Make sure that the example code sets the correct edition. The example should illustrate the previous edition, and show what the migration warning would look like. For example, this lint for a 2024 migration shows an example in 2021:
+
+```rust,ignore
+declare_lint! {
+    /// The `keyword_idents_2024` lint detects ...
+    ///
+    /// ### Example
+    ///
+    /// ```rust,edition2021
+    /// #![warn(keyword_idents_2024)]
+    /// fn gen() {}
+    /// ```
+    ///
+    /// {{produces}}
+}
+```
+
 Migration lints can be either `Allow` or `Warn` by default.
 If it is `Allow`, users usually won't see this warning unless they are doing an edition migration
 manually or there is a problem during the migration.
@@ -334,3 +351,40 @@ In general it is recommended to avoid these special cases except for very high v
 [into-iter]: https://doc.rust-lang.org/nightly/edition-guide/rust-2021/IntoIterator-for-arrays.html
 [panic-macro]: https://doc.rust-lang.org/nightly/edition-guide/rust-2021/panic-macro-consistency.html
 [`non_fmt_panics`]: https://doc.rust-lang.org/nightly/rustc/lints/listing/warn-by-default.html#non-fmt-panics
+
+### Migrating the standard library edition
+
+Updating the edition of the standard library itself roughly involves the following process:
+
+- Wait until the newly stabilized edition has reached beta and the bootstrap compiler has been updated.
+- Apply migration lints. This can be an involved process since some code is in external submodules[^std-submodules], and the standard library makes heavy use of conditional compilation. Also, running `cargo fix --edition` can be impractical on the standard library itself. One approach is to individually add `#![warn(...)]` at the top of each crate for each lint, run `./x check library`, apply the migrations, remove the `#![warn(...)]` and commit each migration separately. You'll likely need to run `./x check` with `--target` for many different targets to get full coverage (otherwise you'll likely spend days or weeks getting CI to pass)[^ed-docker]. See also the [advanced migration guide] for more tips.
+    - Apply migrations to [`backtrace-rs`]. [Example for 2024](https://github.com/rust-lang/backtrace-rs/pull/700). Note that this doesn't update the edition of the crate itself because that is published independently on crates.io, and that would otherwise restrict the minimum Rust version. Consider adding some `#![deny()]` attributes to avoid regressions until its edition gets updated.
+    - Apply migrations to [`stdarch`], and update its edition, and formatting. [Example for 2024](https://github.com/rust-lang/stdarch/pull/1710).
+    - Post PRs to update the backtrace and stdarch submodules, and wait for those to land.
+    - Apply migration lints to the standard library crates, and update their edition. I recommend working one crate at a time starting with `core`. [Example for 2024](https://github.com/rust-lang/rust/pull/138162).
+
+[^std-submodules]: This will hopefully change in the future to pull these submodules into `rust-lang/rust`.
+[^ed-docker]: You'll also likely need to do a lot of testing for different targets, and this is where [docker testing](../tests/docker.md) comes in handy.
+
+[advanced migration guide]: https://doc.rust-lang.org/nightly/edition-guide/editions/advanced-migrations.html
+[`backtrace-rs`]: https://github.com/rust-lang/backtrace-rs/
+[`stdarch`]: https://github.com/rust-lang/stdarch/
+
+## Stabilizing an edition
+
+After the edition team has given the go-ahead, the process for stabilizing an edition is roughly:
+
+- Update [`LATEST_STABLE_EDITION`].
+- Update [`Edition::is_stable`].
+- Hunt and find any document that refers to edition by number, and update it:
+    - [`--edition` flag](https://github.com/rust-lang/rust/blob/master/src/doc/rustc/src/command-line-arguments.md#--edition-specify-the-edition-to-use)
+    - [Rustdoc attributes](https://github.com/rust-lang/rust/blob/master/src/doc/rustdoc/src/write-documentation/documentation-tests.md#attributes)
+- Clean up any tests that use the `//@ edition` header to remove the `-Zunstable-options` flag to ensure they are indeed stable. Note: Ideally this should be automated, see [#133582].
+- Bless any tests that change.
+- Update `lint-docs` to default to the new edition.
+
+See [example for 2024](https://github.com/rust-lang/rust/pull/133349).
+
+[`LATEST_STABLE_EDITION`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_span/edition/constant.LATEST_STABLE_EDITION.html
+[`Edition::is_stable`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_span/edition/enum.Edition.html#method.is_stable
+[#133582]: https://github.com/rust-lang/rust/issues/133582