diff --git a/src/bug-fix-procedure.md b/src/bug-fix-procedure.md index 8702f8aa9..2f5e24716 100644 --- a/src/bug-fix-procedure.md +++ b/src/bug-fix-procedure.md @@ -53,9 +53,9 @@ Please see [the RFC][rfc 1122] for full details! The procedure for making a breaking change is as follows (each of these steps is described in more detail below): -0. Do a **crater run** to assess the impact of the change. -1. Make a **special tracking issue** dedicated to the change. -1. Do not report an error right away. Instead, **issue forwards-compatibility +1. Do a **crater run** to assess the impact of the change. +2. Make a **special tracking issue** dedicated to the change. +3. Do not report an error right away. Instead, **issue forwards-compatibility lint warnings**. - Sometimes this is not straightforward. See the text below for suggestions on different techniques we have employed in the past. @@ -65,7 +65,7 @@ described in more detail below): - Submit PRs to all known affected crates that fix the issue - or, at minimum, alert the owners of those crates to the problem and direct them to the tracking issue -1. Once the change has been in the wild for at least one cycle, we can +4. Once the change has been in the wild for at least one cycle, we can **stabilize the change**, converting those warnings into errors. Finally, for changes to `rustc_ast` that will affect plugins, the general policy diff --git a/src/macro-expansion.md b/src/macro-expansion.md index 7be7fb121..7f50f7f89 100644 --- a/src/macro-expansion.md +++ b/src/macro-expansion.md @@ -48,45 +48,45 @@ iteration, this represents a compile error. Here is the [algorithm][original]: [fef]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_expand/expand/struct.MacroExpander.html#method.fully_expand_fragment [original]: https://github.com/rust-lang/rust/pull/53778#issuecomment-419224049 -0. Initialize an `queue` of unresolved macros. -1. Repeat until `queue` is empty (or we make no progress, which is an error): - 0. [Resolve](./name-resolution.md) imports in our partially built crate as - much as possible. - 1. Collect as many macro [`Invocation`s][inv] as possible from our - partially built crate (fn-like, attributes, derives) and add them to the - queue. - 2. Dequeue the first element, and attempt to resolve it. - 3. If it's resolved: - 0. Run the macro's expander function that consumes a [`TokenStream`] or - AST and produces a [`TokenStream`] or [`AstFragment`] (depending on - the macro kind). (A `TokenStream` is a collection of [`TokenTree`s][tt], - each of which are a token (punctuation, identifier, or literal) or a - delimited group (anything inside `()`/`[]`/`{}`)). - - At this point, we know everything about the macro itself and can - call `set_expn_data` to fill in its properties in the global data; - that is the hygiene data associated with `ExpnId`. (See [the - "Hygiene" section below][hybelow]). - 1. Integrate that piece of AST into the big existing partially built - AST. This is essentially where the "token-like mass" becomes a - proper set-in-stone AST with side-tables. It happens as follows: - - If the macro produces tokens (e.g. a proc macro), we parse into - an AST, which may produce parse errors. - - During expansion, we create `SyntaxContext`s (hierarchy 2). (See - [the "Hygiene" section below][hybelow]) - - These three passes happen one after another on every AST fragment - freshly expanded from a macro: - - [`NodeId`]s are assigned by [`InvocationCollector`]. This - also collects new macro calls from this new AST piece and - adds them to the queue. - - ["Def paths"][defpath] are created and [`DefId`]s are - assigned to them by [`DefCollector`]. - - Names are put into modules (from the resolver's point of - view) by [`BuildReducedGraphVisitor`]. - 2. After expanding a single macro and integrating its output, continue - to the next iteration of [`fully_expand_fragment`][fef]. - 4. If it's not resolved: - 0. Put the macro back in the queue - 1. Continue to next iteration... +1. Initialize an `queue` of unresolved macros. +2. Repeat until `queue` is empty (or we make no progress, which is an error): + 1. [Resolve](./name-resolution.md) imports in our partially built crate as + much as possible. + 2. Collect as many macro [`Invocation`s][inv] as possible from our + partially built crate (fn-like, attributes, derives) and add them to the + queue. + 3. Dequeue the first element, and attempt to resolve it. + 4. If it's resolved: + 1. Run the macro's expander function that consumes a [`TokenStream`] or + AST and produces a [`TokenStream`] or [`AstFragment`] (depending on + the macro kind). (A `TokenStream` is a collection of [`TokenTree`s][tt], + each of which are a token (punctuation, identifier, or literal) or a + delimited group (anything inside `()`/`[]`/`{}`)). + - At this point, we know everything about the macro itself and can + call `set_expn_data` to fill in its properties in the global data; + that is the hygiene data associated with `ExpnId`. (See [the + "Hygiene" section below][hybelow]). + 2. Integrate that piece of AST into the big existing partially built + AST. This is essentially where the "token-like mass" becomes a + proper set-in-stone AST with side-tables. It happens as follows: + - If the macro produces tokens (e.g. a proc macro), we parse into + an AST, which may produce parse errors. + - During expansion, we create `SyntaxContext`s (hierarchy 2). (See + [the "Hygiene" section below][hybelow]) + - These three passes happen one after another on every AST fragment + freshly expanded from a macro: + - [`NodeId`]s are assigned by [`InvocationCollector`]. This + also collects new macro calls from this new AST piece and + adds them to the queue. + - ["Def paths"][defpath] are created and [`DefId`]s are + assigned to them by [`DefCollector`]. + - Names are put into modules (from the resolver's point of + view) by [`BuildReducedGraphVisitor`]. + 3. After expanding a single macro and integrating its output, continue + to the next iteration of [`fully_expand_fragment`][fef]. + 5. If it's not resolved: + 1. Put the macro back in the queue + 2. Continue to next iteration... [defpath]: hir.md#identifiers-in-the-hir [`NodeId`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_ast/node_id/struct.NodeId.html diff --git a/src/part-5-intro.md b/src/part-5-intro.md index faa12f484..f32508d27 100644 --- a/src/part-5-intro.md +++ b/src/part-5-intro.md @@ -21,16 +21,16 @@ Now, we will finally take the MIR and produce some executable machine code. So what do we need to do? -0. First, we need to collect the set of things to generate code for. +1. First, we need to collect the set of things to generate code for. In particular, we need to find out which concrete types to substitute for generic ones, since we need to generate code for the concrete types. Generating code for the concrete types (i.e. emitting a copy of the code for each concrete type) is called _monomorphization_, so the process of collecting all the concrete types is called _monomorphization collection_. -1. Next, we need to actually lower the MIR to a codegen IR +2. Next, we need to actually lower the MIR to a codegen IR (usually LLVM IR) for each concrete type we collected. -2. Finally, we need to invoke the codegen backend, +3. Finally, we need to invoke the codegen backend, which runs a bunch of optimization passes, generates executable code, and links together an executable binary. diff --git a/src/stability.md b/src/stability.md index b7308ee73..85c75fadb 100644 --- a/src/stability.md +++ b/src/stability.md @@ -72,14 +72,14 @@ Furthermore this attribute is needed to mark an intrinsic as callable from To stabilize a feature, follow these steps: -0. Ask a **@T-libs-api** member to start an FCP on the tracking issue and wait for +1. Ask a **@T-libs-api** member to start an FCP on the tracking issue and wait for the FCP to complete (with `disposition-merge`). -1. Change `#[unstable(...)]` to `#[stable(since = "CURRENT_RUSTC_VERSION")]`. -2. Remove `#![feature(...)]` from any test or doc-test for this API. If the feature is used in the +2. Change `#[unstable(...)]` to `#[stable(since = "CURRENT_RUSTC_VERSION")]`. +3. Remove `#![feature(...)]` from any test or doc-test for this API. If the feature is used in the compiler or tools, remove it from there as well. -3. If applicable, change `#[rustc_const_unstable(...)]` to +4. If applicable, change `#[rustc_const_unstable(...)]` to `#[rustc_const_stable(since = "CURRENT_RUSTC_VERSION")]`. -4. Open a PR against `rust-lang/rust`. +5. Open a PR against `rust-lang/rust`. - Add the appropriate labels: `@rustbot modify labels: +T-libs-api`. - Link to the tracking issue and say "Closes #XXXXX".