Revise the stabilization process changes

traviscross · traviscross · commit 14645f015a72 · 2025-07-23T06:16:25.000Z
This PR contains a number of changes to better describe our
stabilization process and policies.  Let's revise this a bit,
editorially, to better describe some of the nuances in our process,
and to capture some additional details we want people to speak to in
their stabilization reports.
diff --git a/src/implementing_new_features.md b/src/implementing_new_features.md
@@ -209,33 +209,33 @@ tests/ui/feature-gates/ --bless`.
 
 ## Call for testing
 
-Once the implementation is complete, the feature will be available to nightly users, but not yet part of stable Rust. This is a good time to write a blog post on [the main Rust blog][rust-blog] and issue a **Call for Testing**.
+Once the implementation is complete, the feature will be available to nightly users but not yet part of stable Rust. This is a good time to write a blog post on [the main Rust blog][rust-blog] and issue a "call for testing".
 
-Some example Call for Testing blog posts:
+Some earlier such blog posts include:
 
 1. [The push for GATs stabilization](https://blog.rust-lang.org/2021/08/03/GATs-stabilization-push/)
 2. [Changes to `impl Trait` in Rust 2024](https://blog.rust-lang.org/2024/09/05/impl-trait-capture-rules.html)
 3. [Async Closures MVP: Call for Testing!](https://blog.rust-lang.org/inside-rust/2024/08/09/async-closures-call-for-testing/)
 
-Alternatively, [*This Week in Rust*][twir] has a [call-for-testing section][twir-cft]. Example:
+Alternatively, [*This Week in Rust*][twir] has a [section][twir-cft] for this. One example of this having been used is:
 
-- [Call for testing on boolean literals as cfg predicates](https://github.com/rust-lang/rust/issues/131204#issuecomment-2569314526).
+- [Call for testing on boolean literals as cfg predicates](https://github.com/rust-lang/rust/issues/131204#issuecomment-2569314526)
 
-Which option to choose might depend on how significant the language change is, though note that [*This Week in Rust*][twir]'s Call for Testing section might be less visible than a dedicated post on the main Rust blog.
+Which option to choose might depend on how significant the language change is, though note that the [*This Week in Rust*][twir] section might be less visible than a dedicated post on the main Rust blog.
 
 ## Affiliated work
 
-Once the feature is supported by rustc, there is other associated work that needs to be done to give users a complete experience. Think of it as the *language toolchain* developer experience, which doesn't only comprise of the language or compiler in isolation.
+Once the feature is supported by rustc, there is other associated work that needs to be done to give users a polished experience when using all of the tools we ship.
 
 - Documenting the language feature in the [Rust Reference][reference].
-- (If applicable) Extending [`rustfmt`] to format any new syntax.
-- (If applicable) Extending [`rust-analyzer`]. This can depend on the nature of the language feature, as some features don't need to be blocked on *full* support.
-   - A blocking concern is when a language feature degrades the user experience simply by existing before its support is implemented in [`rust-analyzer`].
-   - Example blocking concern: new syntax that [`rust-analyzer`] can't parse -> bogus diagnostics, type inference changes -> bogus diagnostics.
+- Extending [`rustfmt`] to format any new syntax (if applicable).
+- Extending [`rust-analyzer`] (if applicable). The extent of this work can depend on the nature of the language feature, as some features don't need to be blocked on *full* support.
+   - When a language feature degrades the user experience simply by existing before support is implemented in [`rust-analyzer`], that may lead the lang team to raise a blocking concern.
+   - Examples of such might include new syntax that [`rust-analyzer`] can't parse or type inference changes it doesn't understand when those lead to bogus diagnostics.
 
 ## Stabilization
 
-The final step in the feature lifecycle is [stabilization][stab], which is when the feature becomes available to all Rust users. At this point, backwards incompatible changes are no longer permitted (modulo soundness bugs and inference changes; see the lang team's [defined semver policies](https://rust-lang.github.io/rfcs/1122-language-semver.html) for full details). To learn more about stabilization, see the [stabilization guide][stab].
+The final step in the feature lifecycle is [stabilization][stab], which is when the feature becomes available to all Rust users. At this point, backward incompatible changes are generally no longer permitted (see the lang team's [defined semver policies](https://rust-lang.github.io/rfcs/1122-language-semver.html) for details). To learn more about stabilization, see the [stabilization guide][stab].
 
 
 [stab]: ./stabilization_guide.md
diff --git a/src/stabilization_guide.md b/src/stabilization_guide.md
@@ -47,27 +47,23 @@ Author a stabilization report using the [template found in this repository][srt]
 
 Stabilization reports summarize:
 
-- The main design decisions and deviations since the RFC was accepted, particularly decisions that were FCP'd or otherwise accepted by the language team.
-    - Quite often, the final stabilized language feature can have significant design deviations from the original RFC text.
+- The main design decisions and deviations since the RFC was accepted, including both decisions that were FCP'd or otherwise accepted by the language team as well as those being presented to the lang team for the first time.
+    - Quite often, the final stabilized language feature can have significant design deviations from the original RFC text. That's OK, but these deviations must be highlighted and explained carefully.
 - The work that has been done since the RFC was accepted, acknowledging the main contributors that helped drive the language feature forward.
 
-The [*Stabilization Template*][srt] includes a series of questions that aim to surface interconnections between this feature and the various Rust teams (lang, types, etc) and also to identify items that are commonly overlooked.
+The [*Stabilization Template*][srt] includes a series of questions that aim to surface connections between this feature and lang's subteams (e.g. types, opsem, lang-docs, etc.) and to identify items that are commonly overlooked.
 
 [srt]: ./stabilization_report_template.md
 
 The stabilization report is typically posted as the main comment on the stabilization PR (see the next section).
 
 ## Stabilization PR for a language feature
 
-*This is for stabilizing language features.  If you are stabilizing a library
-feature, see [the stabilization chapter of the std dev guide][std-guide-stabilization] instead.*
+*This is for stabilizing language features.  If you are stabilizing a library feature, see [the stabilization chapter of the std dev guide][std-guide-stabilization] instead.*
 
-Here is a general guide to how to stabilize a feature --
-every feature is different, of course, so some features may
-require steps beyond what this guide talks about.
+Here is a general guide to how to stabilize a feature -- every feature is different, of course, so some features may require steps beyond what this guide discusses.
 
-Note: Before we stabilize any feature, it's the rule that it
-should appear in the documentation.
+Note: Before the stabilization will be considered by the lang team, there must be a complete PR to the Reference describing the feature, and before the stabilization PR will be merged, this PR must have been reviewed and accepted by the lang-docs team.
 
 ### Updating the feature-gate listing
 
@@ -166,22 +162,24 @@ if something { /* XXX */ }
 
 ## Team nominations
 
-After the stabilization PR is opened with the stabilization report, wait a bit for potential immediate comments. When such immediate comments "simmer down" and you feel the PR is ready for consideration by the lang team, you can [nominate the PR](https://lang-team.rust-lang.org/how_to/nominate.html) to get it on the list for discussion in the next meeting. You should also cc the other interacting teams when applicable to review the language feature being stabilized and the stabilization report:
+When opening the stabilization PR, CC the lang team (`@rust-lang/lang`) and any other teams to whom the feature is relevant, e.g.:
 
-* `@rust-lang/types`, to look for type system interactions
-* `@rust-lang/compiler`, to review implementation robustness
-* `@rust-lang/opsem`, if this feature interacts with unsafe code and can create undefined behavior
-* `@rust-lang/libs-api`, if there are additions to the standard library that affects standard library API or their guarantees
+- `@rust-lang/types`, for type system interactions.
+- `@rust-lang/compiler`, for implementation robustness.
+- `@rust-lang/opsem`, for interactions with unsafe code.
+- `@rust-lang/libs-api`, for changes to the standard library API or its guarantees.
+- `@rust-lang/lang-docs`, for questions about how this should be documented in the Reference.
 
-If you are not an organization member, you can simply ask your assigned reviewer to cc the relevant teams on your behalf.
+After the stabilization PR is opened with the stabilization report, wait a bit for any immediate comments. When such comments "simmer down" and you feel the PR is ready for consideration by the lang team, [nominate the PR](https://lang-team.rust-lang.org/how_to/nominate.html) to get it on the agenda for consideration in an upcoming lang meeting.
+
+If you are not a `rust-lang` organization member, you can ask your assigned reviewer to CC the relevant teams on your behalf.
 
 ## FCP proposed on the PR
 
-Finally, some member of the team responsible for tracking this feature agrees with stabilizing this feature, will
-start the FCP (final-comment-period) process by commenting
+After the lang team and other relevant teams review the stabilization, and after you have answered any questions they may have had, a member of one of the teams may propose to accept the stabilization by commenting:
 
 ```text
 @rfcbot fcp merge
 ```
 
-The rest of the team members will review the proposal. If the final decision is to stabilize, the PR will be reviewed by the compiler team like any other PR.
+Once enough team members have reviewed, the PR will move into a "final comment period". After this period, if no new concerns have been raised, the PR can be merged after implementation review in the usual way.
diff --git a/src/stabilization_report_template.md b/src/stabilization_report_template.md
@@ -2,43 +2,63 @@
 
 > **What is this?**
 >
-> This is a template to use for [stabilization reports](./stabilization_guide.md) of **language features**. It consists of a series of questions that aim to provide the information most commonly needed and to help reviewers be more likely to identify potential problems up front. Not all parts of the template will apply to all stabilizations. Feel free to put N/A if a question doesn't seem to apply to your case.
+> This is a template to use for [stabilization reports](./stabilization_guide.md) of **language features**. It consists of a series of questions that aim to provide the information most commonly needed. This helps reviewers to identify potential problems up front. Not all parts of the template will apply to every stabilizations. Put N/A if a question doesn't apply.
 >
-> You can copy the following template after the separator and edit it as Markdown, replacing the *TODO* placeholders with answers. 
+> Copy the following template after the separator and edit it as Markdown. Replace each *TODO* with answers.
 
 ---
 
 > ## General design
+>
+> ### What is the RFC for this feature?
 
->  ### What is the RFC for this feature and what changes have occurred to the user-facing design since the RFC was finalized?
+*TODO*
+
+> ### Post-RFC changes
+>
+> What user-visible changes have occurred since the RFC was accepted?
 
 *TODO*
 
->  ### What behavior are we committing to that has been controversial? Summarize the major arguments pro/con.
+> ### Key points
+>
+> What behaviors to be stabilized have been most controversial? Summarize the major arguments on all sides.
 
 *TODO*
 
-> ### Are there extensions to this feature that remain unstable? How do we know that we are not accidentally committing to those?
+> ### Nightly extensions
+>
+> Are there extensions to this feature that remain unstable? How do we know that we are not accidentally committing to those?
 
 *TODO*
 
-> ## Has a Call for Testing period been conducted? If so, what feedback was received?
+> ## Feedback
 >
-> Does any OSS nightly users use this feature? For instance, a useful indication might be "search <grep.app> for `#![feature(FEATURE_NAME)]` and had `N` results".
+> ### Call for testing
+>
+> Has a "call for testing" been done? If so, what feedback was received?
 
 *TODO*
 
-> ## Implementation quality
+> ### Nightly use
+>
+> Does any OSS nightly users use this feature? For instance, a useful indication might be "search <grep.app> for `#![feature(FEATURE_NAME)]` and had `N` results".
 
 *TODO*
 
-> ### Summarize the major parts of the implementation and provide links into the code (or to PRs)
+> ## Implementation quality
+>
+> ### Major parts
+>
+> Summarize the major parts of the implementation and provide links into the code (or to PRs).
 >
 > An example for async closures: <https://rustc-dev-guide.rust-lang.org/coroutine-closures.html>.
 
 *TODO*
 
-> ### Summarize existing test coverage of this feature
+> ### Coverage
+>
+> Summarize existing test coverage of this feature.
 >
 > Consider what the "edges" of this feature are.  We're particularly interested in seeing tests that assure us about exactly what nearby things we're not stabilizing.
 >
@@ -56,50 +76,82 @@
 
 *TODO*
 
-> ### What outstanding bugs in the issue tracker involve this feature? Are they stabilization-blocking?
+> ### Outstanding bugs
+>
+> What outstanding bugs in the issue tracker involve this feature? Are they stabilization-blocking?
 
 *TODO*
 
-> ### What FIXMEs are still in the code for that feature and why is it ok to leave them there?
+> ### Outstanding FIXMEs
+>
+> What FIXMEs are still in the code for that feature and why is it ok to leave them there?
 
 *TODO*
 
-> ### Summarize contributors to the feature by name for recognition and assuredness that people involved in the feature agree with stabilization 
+> ### Contributors
+>
+> Summarize contributors to the feature by name for recognition and assuredness that people involved in the feature agree with stabilization.
 
 *TODO*
 
-> ### Which tools need to be adjusted to support this feature. Has this work been done?
->  
-> Consider rustdoc, clippy, rust-analyzer, rustfmt, rustup, docs.rs.
+> ### Tool changes
+>
+> Which tools need to be adjusted to support this feature. Has this work been done?
+>
+> Consider rustdoc (both JSON and HTML), clippy, rust-analyzer, rustfmt, rustup, docs.rs.
 
 *TODO*
 
 > ## Type system and execution rules
 
-> ### What compilation-time checks are done that are needed to prevent undefined behavior?
->  
->  (Be sure to link to tests demonstrating that these tests are being done.)
+> ### Compile-time checks
+>
+> What compilation-time checks are done that are needed to prevent undefined behavior?
+>
+> (Be sure to link to tests demonstrating that these tests are being done.)
 
 *TODO*
 
-> ### Does the feature's implementation need checks to prevent UB or is it sound by default and needs opt in in places to perform the dangerous/unsafe operations? If it is not sound by default, what is the rationale?
+> ### Sound by default?
+>
+> Does the feature's implementation need checks to prevent UB or is it sound by default and needs opt in in places to perform the dangerous/unsafe operations? If it is not sound by default, what is the rationale?
 
 *TODO*
 
-> ### Can users use this feature to introduce undefined behavior, or use this feature to break the abstraction of Rust and expose the underlying assembly-level implementation? (Describe.)
+> ### Breaks the AM?
+>
+> Can users use this feature to introduce undefined behavior, or use this feature to break the abstraction of Rust and expose the underlying assembly-level implementation? (Describe.)
 
 *TODO*
 
-> ### What updates are needed to the reference/specification? (link to PRs when they exist)
+> ### Reference
+>
+> What updates are needed to the Reference? Link to each PR.
 
-*TODO*
+- *TODO*
 
 > ## Common interactions
+>
+> ### Temporaries
+>
+> Does this feature introduce new expressions that can produce temporaries? What are the lifetimes of those temporaries?
 
-> ### Does this feature introduce new expressions and can they produce temporaries? What are the lifetimes of those temporaries?
+*TODO*
+
+> ### Pre-expansion / post-expansion
+>
+> Does this feature raise questions about what should be accepted pre-expansion (e.g. in code covered by `#[cfg(false)]`) versus what should be accepted post-expansion? What decisions were made about this?
 
 *TODO*
 
-> ### What other unstable features may be exposed by this feature?
+> ### SemVer implications
+>
+> Does this feature create any new ways in which library authors must take care to prevent breaking their downstreams when making minor-version releases? Describe these. Are these new hazards "major" or "minor" according to [RFC 1105](https://rust-lang.github.io/rfcs/1105-api-evolution.html)?
+
+*TODO*
+
+> ### Exposing other features
+>
+> Are there any other unstable features whose behavior may be exposed by this feature in any way? What features present the highest risk of that?
 
 *TODO*
