stabilization template, docs

src/SUMMARY.md

@@ -50,7 +50,8 @@
 - [Walkthrough: a typical contribution](./walkthrough.md)
 - [Implementing new language features](./implementing_new_features.md)
 - [Stability attributes](./stability.md)
-- [Stabilizing Features](./stabilization_guide.md)
+- [Stabilizing language features](./stabilization_guide.md)
+    - [Stabilization report template](./stabilization_report_template.md)
 - [Feature Gates](./feature-gates.md)
 - [Coding conventions](./conventions.md)
 - [Procedures for Breaking Changes](./bug-fix-procedure.md)

src/implementing_new_features.md

@@ -204,3 +204,42 @@ tests/ui/feature-gates/ --bless`.
 [here]: ./stabilization_guide.md
 [tracking issue]: #tracking-issues
 [add-feature-gate]: ./feature-gates.md#adding-a-feature-gate
+
+## 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:
+
+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:
+
+- [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.
+
+## 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.
+
+- 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.
+
+## 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].
+
+
+[stab]: ./stabilization_guide.md
+[rust-blog]: https://github.com/rust-lang/blog.rust-lang.org/
+[twir]: https://github.com/rust-lang/this-week-in-rust
+[twir-cft]: https://this-week-in-rust.org/blog/2025/01/22/this-week-in-rust-583/#calls-for-testing
+[`rustfmt`]: https://github.com/rust-lang/rustfmt
+[`rust-analyzer`]: https://github.com/rust-lang/rust-analyzer
+[reference]: https://github.com/rust-lang/reference

src/stabilization_guide.md

@@ -43,55 +43,25 @@ has completed. Meanwhile, we can proceed to the next step.
 
 ## Write a stabilization report
 
-Find the tracking issue of the feature, and create a short
-stabilization report. Essentially this would be a brief summary
-of the feature plus some links to test cases showing it works
-as expected, along with a list of edge cases that came up
-and were considered. This is a minimal "due diligence" that
-we do before stabilizing.
-
-The report should contain:
-
-- A summary, showing examples (e.g. code snippets) what is
-  enabled by this feature.
-- Links to test cases in our test suite regarding this feature
-  and describe the feature's behavior on encountering edge cases.
-- Links to the documentations (the PRs we have made in the
-  previous steps).
-- Any other relevant information.
-- The resolutions of any unresolved questions if the stabilization
-  is for an RFC.
-
-Examples of stabilization reports can be found in
-[rust-lang/rust#44494][report1] and [rust-lang/rust#28237][report2] (these links
-will bring you directly to the comment containing the stabilization report).
-
-[report1]: https://github.com/rust-lang/rust/issues/44494#issuecomment-360191474
-[report2]: https://github.com/rust-lang/rust/issues/28237#issuecomment-363374130
-
-## FCP
-
-If any member of the team responsible for tracking this
-feature agrees with stabilizing this feature, they will
-start the FCP (final-comment-period) process by commenting
+Author a stabilization report using the [template found in this repository][srt].
 
-```text
-@rfcbot fcp merge
-```
+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 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 rest of the team members will review the proposal. If the final
-decision is to stabilize, we proceed to do the actual code modification.
+[srt]: ./stabilization_report_template.md
 
-## Stabilization PR
+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.*
 
-Once we have decided to stabilize a feature, we need to have
-a PR that actually makes that stabilization happen. These kinds
-of PRs are a great way to get involved in Rust, as they take
-you on a little tour through the source code.
-
 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.
@@ -151,8 +121,7 @@ same `compiler/rustc_ast_passes/src/feature_gate.rs`.
 For example, you might see code like this:
 
 ```rust,ignore
-gate_feature_post!(&self, pub_restricted, span,
- "`pub(restricted)` syntax is experimental");
+gate_all!(pub_restricted, "`pub(restricted)` syntax is experimental");
 ```
 
 This `gate_feature_post!` macro prints an error if the
@@ -162,7 +131,7 @@ now that `#[pub_restricted]` is stable.
 For more subtle features, you may find code like this:
 
 ```rust,ignore
-if self.tcx.sess.features.borrow().pub_restricted { /* XXX */ }
+if self.tcx.features().async_fn_in_dyn_trait() { /* XXX */ }
 ```
 
 This `pub_restricted` field (obviously named after the feature)
@@ -194,3 +163,25 @@ if something { /* XXX */ }
 [Rust by Example]: https://github.com/rust-lang/rust-by-example
 [`Unstable Book`]: https://doc.rust-lang.org/unstable-book/index.html
 [`src/doc/unstable-book`]: https://github.com/rust-lang/rust/tree/master/src/doc/unstable-book
+
+## 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:
+
+* `@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
+
+If you are not an organization member, you can simply 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
+
+```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.

src/stabilization_report_template.md

@@ -0,0 +1,105 @@
+# Stabilization report template
+
+> **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.
+>
+> You can copy the following template after the separator and edit it as Markdown, replacing the *TODO* placeholders with answers. 
+
+---
+
+> ## General design
+
+>  ### What is the RFC for this feature and what changes have occurred to the user-facing design since the RFC was finalized?
+
+*TODO*
+
+>  ### What behavior are we committing to that has been controversial? Summarize the major arguments pro/con.
+
+*TODO*
+
+> ### 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?
+>
+> 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*
+
+> ## Implementation quality
+
+*TODO*
+
+> ### 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
+>
+> 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.
+>
+> Within each test, include a comment at the top describing the purpose of the test and what set of invariants it intends to demonstrate. This is a great help to those reviewing the tests at stabilization time.
+>
+> - What does the test coverage landscape for this feature look like?
+>   - Tests for compiler errors when you use the feature wrongly or make mistakes?
+>   - Tests for the feature itself:
+>       - Limits of the feature (so failing compilation)
+>       - Exercises of edge cases of the feature
+>       - Tests that checks the feature works as expected (where applicable, `//@ run-pass`).
+>   - Are there any intentional gaps in test coverage?
+>
+> Link to test folders or individual tests (ui/codegen/assembly/run-make tests, etc.).
+
+*TODO*
+
+> ### 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?
+
+*TODO*
+
+> ### 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.
+
+*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.)
+
+*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?
+
+*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.)
+
+*TODO*
+
+> ### What updates are needed to the reference/specification? (link to PRs when they exist)
+
+*TODO*
+
+> ## Common interactions
+
+> ### Does this feature introduce new expressions and can they produce temporaries? What are the lifetimes of those temporaries?
+
+*TODO*
+
+> ### What other unstable features may be exposed by this feature?
+
+*TODO*