Revise stabilization text

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 and consider when reviewing stabilization
PRs.

Author: traviscross

src/implementing_new_features.md

@@ -6,7 +6,7 @@ When you want to implement a new significant feature in the compiler,
 you need to go through this process to make sure everything goes
 smoothly.
 
-**NOTE: this section is for *language* features, not *library* features,
+**NOTE: This section is for *language* features, not *library* features,
 which use [a different process].**
 
 See also [the Rust Language Design Team's procedures][lang-propose] for
@@ -92,32 +92,37 @@ make the necessary changes, and are satisfied, we expose it to
 the world using the stabilization process described [here].
 Until then, the feature is not set in stone: every part of the
 feature can be changed, or the feature might be completely
-rewritten or removed. Features are not supposed to gain tenure
-by being unstable and unchanged for a year.
+rewritten or removed. Features do not gain tenure by being
+unstable and unchanged for long periods of time.
 
 ###  Tracking Issues
 
-To keep track of the status of an unstable feature, the
-experience we get while using it on nightly, and of the
-concerns that block its stabilization, every feature-gate
-needs a tracking issue. General discussions about the feature should be done on the tracking issue.
+To keep track of the status of an unstable feature, the experience we get while using it on
+nightly, and of the concerns that block its stabilization, every feature-gate needs a tracking
+issue. When creating issues and PRs related to the feature, reference this tracking issue, and when there are updates about the feature's progress, post those to the tracking issue.
 
-For features that have an RFC, you should use the RFC's
-tracking issue for the feature.
+For features that are part of an accept RFC or approved lang experiment, use the tracking issue for that.
 
-For other features, you'll have to make a tracking issue
-for that feature. The issue title should be "Tracking issue
-for YOUR FEATURE". Use the ["Tracking Issue" issue template][template].
+For other features, create a tracking issue for that feature. The issue title should be "Tracking
+issue for YOUR FEATURE". Use the ["Tracking Issue" issue template][template].
 
 [template]: https://github.com/rust-lang/rust/issues/new?template=tracking_issue.md
 
+### Lang experiments
+
+To land in the compiler, features that have user-visible effects on the language (even unstable ones) must either be part of an accepted RFC or an approved [lang experiment].
+
+To propose a new lang experiment, open an issue in `rust-lang/rust` that describes the motivation and the intended solution. If it's accepted, this issue will become the tracking issue for the experiment, so use the tracking issue [template] while also including these other details. Nominate the issue for the lang team and CC `@rust-lang/lang`. When the experiment is approved, the tracking issue will be marked as `B-experimental`.
+
+Feature flags related to a lang experiment must be marked as `incomplete` until an RFC is accepted for the feature.
+
+[lang experiment]: https://lang-team.rust-lang.org/how_to/experiment.html
+
 ##  Stability in code
 
-The below steps needs to be followed in order to implement
-a new unstable feature:
+The below steps needs to be followed in order to implement a new unstable feature:
 
-1. Open a [tracking issue] -
-   if you have an RFC, you can use the tracking issue for the RFC.
+1. Open or identify the [tracking issue]. For features that are part of an accept RFC or approved lang experiment, use the tracking issue for that.
 
    The tracking issue should be labeled with at least `C-tracking-issue`.
    For a language feature, a label `F-feature_name` should be added as well.
@@ -160,6 +165,8 @@ a new unstable feature:
    (incomplete, deref_patterns, "CURRENT_RUSTC_VERSION", Some(87121), None),
    ```
 
+   Feature flags related to a lang experiment must be marked as `incomplete` until an RFC is accepted for the feature.
+
    To avoid [semantic merge conflicts], please use `CURRENT_RUSTC_VERSION` instead of `1.70` or
    another explicit version number.
 
@@ -176,16 +183,16 @@ a new unstable feature:
 
    For features introducing new syntax, pre-expansion gating should be used instead.
    During parsing, when the new syntax is parsed, the symbol must be inserted to the
-   current crate's [`GatedSpans`] via `self.sess.gated_span.gate(sym::my_feature, span)`. 
-   
-   After being inserted to the gated spans, the span must be checked in the 
+   current crate's [`GatedSpans`] via `self.sess.gated_span.gate(sym::my_feature, span)`.
+
+   After being inserted to the gated spans, the span must be checked in the
    [`rustc_ast_passes::feature_gate::check_crate`] function, which actually denies
-   features. Exactly how it is gated depends on the exact type of feature, but most 
-   likely will use the `gate_all!()` macro. 
+   features. Exactly how it is gated depends on the exact type of feature, but most
+   likely will use the `gate_all!()` macro.
 
 1. Add a test to ensure the feature cannot be used without
    a feature gate, by creating `tests/ui/feature-gates/feature-gate-$feature_name.rs`.
-   You can generate the corresponding `.stderr` file by running `./x test 
+   You can generate the corresponding `.stderr` file by running `./x test
 tests/ui/feature-gates/ --bless`.
 
 1. Add a section to the unstable book, in
@@ -209,33 +216,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
+## Polishing
 
-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.
+Giving users a polished experience means more than just implementing the feature in rustc. We need to think about all of the tools and resources that we ship. This work includes:
 
 - 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

src/stabilization_guide.md

@@ -1,16 +1,19 @@
 # Request for stabilization
 
-**NOTE**: this page is about stabilizing *language* features.
-For stabilizing *library* features, see [Stabilizing a library feature].
+**NOTE**: This page is about stabilizing *language* features. For stabilizing *library* features, see [Stabilizing a library feature].
 
 [Stabilizing a library feature]: ./stability.md#stabilizing-a-library-feature
 
-Once an unstable feature has been well-tested with no outstanding
-concern, anyone may push for its stabilization. It involves the
-following steps:
+Once an unstable feature has been well-tested with no outstanding concerns, anyone may push for its stabilization. It involves the following steps:
 
 <!-- toc -->
 
+## Write an RFC, if needed
+
+If the feature was part of a [lang experiment], the lang team must first accept an RFC for the feature before it can be stabilized.
+
+[lang experiment]: https://lang-team.rust-lang.org/how_to/experiment.html
+
 ## Documentation PRs
 
 <a id="updating-documentation"></a>
@@ -26,14 +29,9 @@ If there wasn't documentation there, it needs to be added.
 
 Places that may need updated documentation:
 
-- [The Reference]: This must be updated, in full detail.
-- [The Book]: This may or may not need updating, depends.
-    If you're not sure, please open an issue on this repository
-    and it can be discussed.
-- standard library documentation: As needed. Language features
-    often don't need this, but if it's a feature that changes
-    how good examples are written, such as when `?` was added
-    to the language, updating examples is important.
+- [The Reference]: This must be updated, in full detail, and a member of the lang-docs team must review and approve the PR before the stabilization can be merged.
+- [The Book]: This may or may not need updating; it depends.  If you're not sure, please open an issue on this repository and it can be discussed.
+- Standard library documentation: As needed. Language features often don't need this, but if it's a feature that changes how idiomatic examples are written, such as when `?` was added to the language, updating these in the library documentation is important.
 - [Rust by Example]: As needed.
 
 Prepare PRs to update documentation involving this new feature
@@ -45,29 +43,23 @@ has completed. Meanwhile, we can proceed to the next step.
 
 Author a stabilization report using the [template found in this repository][srt].
 
-Stabilization reports summarize:
+The stabilization reports summarizes:
 
-- 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.
+    - Often, the final stabilized language feature has significant design deviations from the original RFC. 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
+## Stabilization PR
 
-*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.*
+Every feature is different, and some may require steps beyond what this guide discusses.
 
-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.
-
-Note: Before we stabilize any feature, it's the rule that it
-should appear in the documentation.
+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 approved by the lang-docs team.
 
 ### Updating the feature-gate listing
 
@@ -94,11 +86,11 @@ When it is done, it should look like:
 
 (Even though you will encounter version numbers in the file of past changes,
 you should not put the rustc version you expect your stabilization to happen in,
-but instead `CURRENT_RUSTC_VERSION`)
+but instead use `CURRENT_RUSTC_VERSION`.)
 
 ### Removing existing uses of the feature-gate
 
-Next search for the feature string (in this case, `pub_restricted`)
+Next, search for the feature string (in this case, `pub_restricted`)
 in the codebase to find where it appears. Change uses of
 `#![feature(XXX)]` from the `std` and any rustc crates (this includes test folders
 under `library/` and `compiler/` but not the toplevel `tests/` one) to be
@@ -116,8 +108,8 @@ simply remove the test.
 Most importantly, remove the code which flags an error if the
 feature-gate is not present (since the feature is now considered
 stable). If the feature can be detected because it employs some
-new syntax, then a common place for that code to be is in the
-same `compiler/rustc_ast_passes/src/feature_gate.rs`.
+new syntax, then a common place for that code to be is in
+`compiler/rustc_ast_passes/src/feature_gate.rs`.
 For example, you might see code like this:
 
 ```rust,ignore
@@ -166,22 +158,37 @@ 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`, for type system interactions.
+- `@rust-lang/opsem`, for interactions with unsafe code.
+- `@rust-lang/compiler`, for implementation robustness.
+- `@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.
 
-* `@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
+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 an organization member, you can simply ask your assigned reviewer to cc the relevant teams on your behalf.
+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
+## Proposed FCP 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". If no new concerns are raised, this period will complete and the PR can be merged after implementation review in the usual way.
+
+## Reviewing and merging stabilizations
+
+On a stabilization, before giving it the `r+`, ensure that the PR:
+
+- Matches what the team proposed for stabilization.
+- Includes any changes the team decided to request along the way in order to resolve or avoid concerns.
+- Is otherwise exactly what is described in the stabilization report and in any relevant RFCs or prior lang FCPs.
+- Does not expose on stable behaviors other than those specified and accepted for stabilization.
+- Has sufficient tests to convincingly demonstrate these things.
+- Is accompanied by a PR to the Reference than has been reviewed and approved by a member of lang-docs.
+
+In particular, when reviewing the PR, keep an eye out for any user-visible detail that the lang team failed to consider and specify. If you find one, describe it and nominate the PR for the lang team.