rustc-dev-guide subtree update

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

@@ -1 +1 @@
-da86f4d0726be475afbbffe40cb2f65741c51ad3
+e64c8a664d9da54fc239cd4404cbf67f0d624326

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

@@ -53,6 +53,9 @@
 - [About the compiler team](./compiler-team.md)
 - [Using Git](./git.md)
 - [Mastering @rustbot](./rustbot.md)
+- [Running LLMs](./llm-guidance.md)
+    - [Writing code with LLMs](./llm-guidance/writing.md)
+    - [Reviewing code with LLMs](./llm-guidance/reviewing.md)
 - [Walkthrough: a typical contribution](./walkthrough.md)
 - [Implementing new language features](./implementing-new-features.md)
 - [Stability guarantees](./stability-guarantees.md)

src/doc/rustc-dev-guide/src/about-this-guide.md

@@ -74,6 +74,7 @@ You might also find the following sites useful:
 
 - [rustc API docs] -- rustdoc documentation for the compiler, devtools, and internal tools
 - [Forge] -- contains documentation about Rust infrastructure, team procedures, and more
+- [`rust-lang/rust`]'s [LLM policy]
 - [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.
@@ -95,7 +96,7 @@ You might also find the following sites useful:
   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!
 
-
+[LLM policy]: https://forge.rust-lang.org/policies/llm-usage.html
 [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
@@ -115,3 +116,4 @@ You might also find the following sites useful:
 [std-dev-guide]: https://std-dev-guide.rust-lang.org/
 [rust-analyzer book]: https://rust-analyzer.github.io/book/
 [z]: https://rust-lang.zulipchat.com/#narrow/stream/131828-t-compiler
+[`rust-lang/rust`]: https://github.com/rust-lang/rust/

src/doc/rustc-dev-guide/src/appendix/glossary.md

@@ -3,6 +3,7 @@
 Term                                           | Meaning
 -----------------------------------------------|--------
 <span id="1zst">1-ZST</span>                   |  A *one-aligned [zero-sized type](#zst)*. A type of size zero with an [alignment][size-align] of one.
+<span id="abby">abby</span>                    | Short for [_assumptions on binders_](https://github.com/rust-lang/project-assumptions-on-binders). Alternatively: `a-bi`, though this is very close to ABI.
 <span id="arena">arena, arena allocation</span> |  An _arena_ is a large memory buffer from which other memory allocations are made. This style of allocation is called _arena allocation_. See [this chapter](../memory.md) for more info.
 <span id="afidt">AFIDT</span>                  |  Short for _async function in `dyn Trait`_. See also [AFIT](#afit).
 <span id="afit">AFIT</span>                    |  Short for _async function in trait_. They desugar to [RPITITs](#rpitit).

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

@@ -372,7 +372,7 @@ Finally, `MAGIC_EXTRA_RUSTFLAGS` bypasses the
 
 - `RUSTDOCFLAGS`, `RUSTDOCFLAGS_BOOTSTRAP` and `RUSTDOCFLAGS_NOT_BOOTSTRAP` are
   analogous to `RUSTFLAGS`, but for `rustdoc`.
-- `CARGOFLAGS` will pass arguments to cargo itself (e.g. `--timings`).
+- `CARGOFLAGS` will pass arguments to cargo itself.
   `CARGOFLAGS_BOOTSTRAP` and `CARGOFLAGS_NOT_BOOTSTRAP` work analogously to `RUSTFLAGS_BOOTSTRAP`.
 - `--test-args` will pass arguments through to the test runner.
   For `tests/ui`,

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

@@ -520,6 +520,12 @@ This is used for [RFCs], issues, and pull requests.
 [rfcbot]: https://github.com/anp/rfcbot-rs/
 [RFCs]: https://github.com/rust-lang/rfcs
 
+## LLM policy
+
+See [Forge][LLM policy].
+
+[LLM policy]: https://forge.rust-lang.org/policies/llm-usage.html
+
 ## Helpful links and information
 
 This section has moved to the ["About this guide"] chapter.

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

@@ -141,6 +141,35 @@ if foo {
 
 If you want to leave a note in the codebase, use `// FIXME` instead.
 
+### Follow the style of surrounding code
+
+Use existing helpers and avoid duplicating logic or validation.
+
+### [Avoid duplicated sources of truth](https://react.dev/learn/choosing-the-state-structure)
+
+Trying to keep data in sync between two different places is a code smell.
+
+### Use types to enforce invariants
+
+When practical, [make invalid states unrepresentable](https://kentcdodds.com/blog/make-impossible-states-impossible), [not just checked at construction time](https://lexi-lambda.github.io/blog/2020/11/01/names-are-not-type-safety/).
+
+### Write useful comments
+
+[Write comments that say *why*][mit-comment-style] you have done a thing, not *what* you have done.
+It's ok to go into detail about non-obvious bugs.
+
+[mit-comment-style]: https://mitcommlab.mit.edu/broad/commkit/coding-and-comment-style/
+
+### Preserve existing behavior
+
+Consider platform differences and error cases.
+Look for relevant tests that exercise the edge cases.
+
+### Work in small steps
+
+Work in small, independently testable steps.
+Run the relevant tests after every meaningful change, so you know where you first went wrong.
+
 <a id="cio"></a>
 
 ## Using crates from crates.io
@@ -159,11 +188,13 @@ you rename a method, then put that rename into its own commit, along
 with the renames of all the uses.
 
 **More commits is usually better.** If you are doing a large change,
-it's almost always better to break it up into smaller steps that can be independently understood.
+it's almost always better to break it up into smaller steps that can be [independently understood][atomic commits].
 The one thing to be aware of is that if
 you introduce some code following one strategy, then change it
 dramatically (versus adding to it) in a later commit, that 'back-and-forth' can be confusing.
 
+[atomic commits]: https://github.blog/developer-skills/github/write-better-commits-build-better-projects/#%e2%9a%9b%ef%b8%8f-resize-and-stabilize-the-commits
+
 **Format liberally.** While only the final commit of a PR must be correctly
 formatted, it is both easier to review and less noisy to format each commit
 individually using `./x fmt`.

src/doc/rustc-dev-guide/src/debuginfo/testing.md

@@ -1,7 +1,7 @@
 # Testing
 
-The debug info test suite is undergoing a substantial rewrite. This section will be filled out as
-the rewrite makes progress.
+The debug info test suite is undergoing a substantial rewrite.
+This section will be filled out as the rewrite makes progress.
 
 Please see [this tracking issue][148483] for more information.
 

src/doc/rustc-dev-guide/src/diagnostics/diagnostic-structs.md

@@ -135,12 +135,12 @@ tcx.dcx().emit_err(FieldAlreadyDeclared {
   - `code = "..."` (_Optional_)
     - Specifies the error code.
 - `#[note("message")]` (_Optional_)
-  - _Applied to struct or struct fields of type `Span`, `Option<()>` or `()`._
+  - _Applied to struct or struct fields of type `Span`, `Option<()>`, `bool`, or `()`._
   - Adds a note subdiagnostic.
   - Value is the note's message.
   - If applied to a `Span` field, creates a spanned note.
 - `#[help("message")]` (_Optional_)
-  - _Applied to struct or struct fields of type `Span`, `Option<()>` or `()`._
+  - _Applied to struct or struct fields of type `Span`, `Option<()>`, `bool`, or `()`._
   - Adds a help subdiagnostic.
   - Value is the help message.
   - If applied to a `Span` field, creates a spanned help.
@@ -149,7 +149,7 @@ tcx.dcx().emit_err(FieldAlreadyDeclared {
   - Adds a label subdiagnostic.
   - Value is the label's message.
 - `#[warning("message")]` (_Optional_)
-  - _Applied to struct or struct fields of type `Span`, `Option<()>` or `()`._
+  - _Applied to struct or struct fields of type `Span`, `Option<()>`, `bool`, or `()`._
   - Adds a warning subdiagnostic.
   - Value is the warning's message.
 - `#[suggestion{,_hidden,_short,_verbose}("message", code = "...", applicability = "...")]`

src/doc/rustc-dev-guide/src/diagnostics/error-guaranteed.md

@@ -1,33 +1,33 @@
 # `ErrorGuaranteed`
-The previous sections have been about the error message that a user of the
-compiler sees. But emitting an error can also have a second important side
-effect within the compiler source code: it generates an
-[`ErrorGuaranteed`][errorguar].
+
+The previous sections have been about the error message that a user of the compiler sees.
+But emitting an error can also have a second important side
+effect within the compiler source code: it generates an [`ErrorGuaranteed`].
 
 `ErrorGuaranteed` is a zero-sized type that is unconstructable outside of the
-[`rustc_errors`][rerrors] crate. It is generated whenever an error is reported
+[`rustc_errors`] crate.
+It is generated whenever an error is reported
 to the user, so that if your compiler code ever encounters a value of type
-`ErrorGuaranteed`, the compilation is _statically guaranteed to fail_. This is
-useful for avoiding unsoundness bugs because you can statically check that an
+`ErrorGuaranteed`, the compilation is _statically guaranteed to fail_.
+This is useful for avoiding unsoundness bugs because you can statically check that an
 error code path leads to a failure.
 
 There are some important considerations about the usage of `ErrorGuaranteed`:
 
-* It does _not_ convey information about the _kind_ of error. For example, the
-  error may be due (indirectly) to a delayed bug or other compiler error.
+* It does _not_ convey information about the _kind_ of error.
+  For example, the error may be due (indirectly) to a delayed bug or other compiler error.
   Thus, you should not rely on
-  `ErrorGuaranteed` when deciding whether to emit an error, or what kind of error
-  to emit.
+  `ErrorGuaranteed` when deciding whether to emit an error, or what kind of error to emit.
 * `ErrorGuaranteed` should not be used to indicate that a compilation _will
-  emit_ an error in the future. It should be used to indicate that an error
-  _has already been_ emitted -- that is, the [`emit()`][emit] function has
-  already been called.  For example, if we detect that a future part of the
+  emit_ an error in the future.
+  It should be used to indicate that an error
+  _has already been_ emitted -- that is, the [`emit()`][emit] function has already been called.
+  For example, if we detect that a future part of the
   compiler will error, we _cannot_ use `ErrorGuaranteed` unless we first emit
   an error or delayed bug ourselves.
 
-Thankfully, in most cases, it should be statically impossible to abuse
-`ErrorGuaranteed`.
+Thankfully, in most cases, it should be statically impossible to abuse `ErrorGuaranteed`.
 
-[errorguar]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_errors/struct.ErrorGuaranteed.html
-[rerrors]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_errors/index.html
+[`ErrorGuaranteed`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_errors/struct.ErrorGuaranteed.html
+[`rustc_errors`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_errors/index.html
 [emit]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_errors/diagnostic/struct.Diag.html#method.emit

src/doc/rustc-dev-guide/src/getting-started.md

@@ -48,6 +48,8 @@ But avoid using LLM tools that generate long, complex words.
 In daily teamwork, **simple and clear words** are best for easy understanding.
 Even small typos or grammar mistakes can make you seem more human, and people connect better with humans.
 
+See also [our LLM policy](https://forge.rust-lang.org/policies/llm-usage.html).
+
 ### Experts
 
 Not all `t-compiler` members are experts on all parts of `rustc`;

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

@@ -23,8 +23,8 @@ supports comparisons for doing range checks, such as `span.edition() >= Edition:
 ### Adding a new edition
 
 Adding a new edition mainly involves adding a variant to the [`Edition`] enum and then fixing
-everything that is broken. See [#94461](https://github.com/rust-lang/rust/pull/94461) for an
-example.
+everything that is broken.
+See [#94461](https://github.com/rust-lang/rust/pull/94461) for an example.
 
 ### Features and Edition stability
 
@@ -35,7 +35,8 @@ When adding a new feature, there are two options you can choose for how to handl
 future edition:
 
 - Just check the edition of the span like `span.at_least_rust_20xx()` (see [Edition hygiene]) or the
-  [`Session::edition`]. This will implicitly depend on the stability of the edition itself to
+  [`Session::edition`].
+  This will implicitly depend on the stability of the edition itself to
   indicate that your feature is available.
 - Place your new behavior behind a [feature gate].
 
@@ -71,7 +72,8 @@ There are a few different options for doing feature checks:
   or just remove the feature check altogether and just check `span.at_least_rust_20xx()`.
 
 If you need to do the feature gating in multiple places, consider placing the check in a single
-function so that there will only be a single place to update. For example:
+function so that there will only be a single place to update.
+For example:
 
 ```rust,ignore
 // An example from Edition 2021 disjoint closure captures.
@@ -93,7 +95,8 @@ Within [`Lexer`], tokens can be modified based on edition-specific behavior.
 For example, C-String literals like `c"foo"` are split into multiple tokens in editions before 2021.
 This is also where things like reserved prefixes are handled for the 2021 edition.
 
-Edition-specific parsing is relatively rare. One example is `async fn` which checks the span of the
+Edition-specific parsing is relatively rare.
+One example is `async fn` which checks the span of the
 token to determine if it is the 2015 edition, and emits an error in that case.
 This can only be done if the syntax was already invalid.
 
@@ -190,7 +193,9 @@ 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:
+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! {
@@ -245,14 +250,16 @@ afterwards.
 This should generally be used sparingly, as there are other options:
 
 - Small impact stylistic changes unrelated to an edition can just make the lint `Warn` on all
-  editions. If you want people to adopt a different way to write things, then go ahead and commit to
+  editions.
+  If you want people to adopt a different way to write things, then go ahead and commit to
   having it show up for all projects.
 
   Beware that if a new warn-by-default lint hits many projects, it can be very disruptive and
   frustrating for users.
 
 - Change the new style to be a hard error in the new edition, and use a [migration lint] to
-  automatically convert projects to the new style. For example,
+  automatically convert projects to the new style.
+  For example,
   [`ellipsis_inclusive_range_patterns`] is a hard error in 2021, and warns in all previous editions.
 
   Beware that these cannot be added after the edition stabilizes.
@@ -354,11 +361,22 @@ In general it is recommended to avoid these special cases except for very high v
 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).
+- 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).
+    - Apply migration lints to the standard library crates, and update their edition.
+      It is recommended to work 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.
@@ -376,7 +394,8 @@ After the edition team has given the go-ahead, the process for stabilizing an ed
 - Hunt and find any document that refers to edition by number, and update it:
     - [`--edition` flag](https://github.com/rust-lang/rust/blob/HEAD/src/doc/rustc/src/command-line-arguments.md#--edition-specify-the-edition-to-use)
     - [Rustdoc attributes](https://github.com/rust-lang/rust/blob/HEAD/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].
+- 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.