stabilization template, docs

Author: Niko Matsakis

src/implementing_new_features.md

@@ -204,3 +204,22 @@ 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 [one of the Rust blogs](https://github.com/rust-lang/blog.rust-lang.org/) and issue a call for testing (here are two example [blog](https://blog.rust-lang.org/inside-rust/2024/08/09/async-closures-call-for-testing.html) [posts](https://blog.rust-lang.org/2024/09/05/impl-trait-capture-rules.html) to give you the idea). The post should highlight how the feature works, what areas you'd like people to play with, and how they can supply feedback.
+
+## 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:
+
+* Extending rustfmt to format any new syntax;
+* Extending rust-analyzer;
+* Documenting the feature in the Rust reference;
+* ...
+
+## 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

src/stabilization_guide.md

@@ -43,44 +43,14 @@ 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].
+Stabilization reports summarize the work that has been done since the RFC.
+The [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.
 
-```text
-@rfcbot fcp merge
-```
+[srt]: ./stabilization_report_template.md
 
-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.
+The stabilization report is typically posted as the main comment on the stabilization PR (see the next section).
+If you'd like to develop the stabilization report incrementally, we recommend adding it to 
 
 ## Stabilization PR
 
@@ -194,3 +164,23 @@ 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
+
+## Lang team nomination
+
+When 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 to review the report:
+
+* `@rust-lang/types`, to look for type system interactions
+* `@rust-lang/compiler`, to vouch for implementation quality
+* `@rust-lang/opsem`, but only if this feature interacts with unsafe code and can create undefined behavior
+* `@rust-lang/libs-api`, but only if there are additions to the standard library
+
+## 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,54 @@
+# Stabilization report template
+
+> **What is this?** This is a template to use for [stabilization reports](./stabilization_guide.md). 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.
+
+## General design
+
+### What is the RFC for this feature and what changes have occurred to the user-facing design since the RFC was finalized?
+
+### What behavior are we committing to that has been controversial? Summarize the major arguments pro/con.
+
+### Are there extensions to this feature that remain unstable? How do we know that we are not accidentally committing to those?
+
+## Has a call-for-testing period been conducted? If so, what feedback was received?
+
+## Implementation quality
+
+### 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
+
+### Summarize existing test coverage of this feature
+
+- What does the test coverage landscape for this feature look like?
+  - (Positive/negative) Behavioral tests?
+  - (Positive/negative) Interface tests? (e.g. compiler cli interface)
+  - Maybe link to test folders or individual tests (ui/codegen/assembly/run-make tests, etc.)
+  - Are there any (intentional/unintentional) gaps in test coverage?
+
+### What outstanding bugs in the issue tracker involve this feature? Are they stabilization-blocking?
+
+### Summarize contributors to the feature by name for recognition and assuredness that people involved in the feature agree with stabilization 
+
+### What FIXMEs are still in the code for that feature and why is it ok to leave them there?
+
+### Which tools need to be adjusted to support this feature. Has this work been done?
+
+*Consider rustdoc, clippy, rust-analyzer, rustfmt, rustup, docs.rs.*
+
+## 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.)
+
+### Can users use this feature to introduce undefined behavior? (Describe.)
+
+### What updates are needed to the reference/specification? (link to PRs when they exist)
+
+## Common interactions
+
+### Does this feature introduce new expressions and can they produce temporaries? What are the lifetimes of those temporaries?
+
+### What other unstable features may be exposed by this feature?
+