From e4ee951653734f09ef3c6fa8ae86588d71fe6ffa Mon Sep 17 00:00:00 2001 From: Niko Matsakis Date: Thu, 23 Jan 2025 20:14:53 +0000 Subject: [PATCH 1/5] stabilization template, docs --- src/implementing_new_features.md | 19 +++++++++ src/stabilization_guide.md | 62 ++++++++++++---------------- src/stabilization_report_template.md | 54 ++++++++++++++++++++++++ 3 files changed, 99 insertions(+), 36 deletions(-) create mode 100644 src/stabilization_report_template.md diff --git a/src/implementing_new_features.md b/src/implementing_new_features.md index d87afeaed..ace6e5117 100644 --- a/src/implementing_new_features.md +++ b/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 diff --git a/src/stabilization_guide.md b/src/stabilization_guide.md index f875c6874..213280cce 100644 --- a/src/stabilization_guide.md +++ b/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. diff --git a/src/stabilization_report_template.md b/src/stabilization_report_template.md new file mode 100644 index 000000000..28d5ce0cc --- /dev/null +++ b/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? + From c63baadda59ddb73ac797f042eab44ae9887cf1e Mon Sep 17 00:00:00 2001 From: Niko Matsakis Date: Thu, 23 Jan 2025 16:48:34 -0500 Subject: [PATCH 2/5] Update src/implementing_new_features.md --- src/implementing_new_features.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/implementing_new_features.md b/src/implementing_new_features.md index ace6e5117..4e09e0602 100644 --- a/src/implementing_new_features.md +++ b/src/implementing_new_features.md @@ -207,7 +207,7 @@ 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 [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. +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 three [example](https://blog.rust-lang.org/2021/08/03/GATs-stabilization-push.html) [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 From 32824bfe35bdcae93eeb8fd1c2b3da32e41070ab Mon Sep 17 00:00:00 2001 From: Niko Matsakis Date: Tue, 28 Jan 2025 10:52:51 -0500 Subject: [PATCH 3/5] Update src/stabilization_report_template.md Co-authored-by: lcnr --- src/stabilization_report_template.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/stabilization_report_template.md b/src/stabilization_report_template.md index 28d5ce0cc..194f81fa3 100644 --- a/src/stabilization_report_template.md +++ b/src/stabilization_report_template.md @@ -28,10 +28,10 @@ An example for async closures: https://rustc-dev-guide.rust-lang.org/coroutine-c ### 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? +### Summarize contributors to the feature by name for recognition and assuredness that people involved in the feature agree with stabilization + ### Which tools need to be adjusted to support this feature. Has this work been done? *Consider rustdoc, clippy, rust-analyzer, rustfmt, rustup, docs.rs.* From 6c99b7501afeebb2dcdceb9aa15feee8988d205f Mon Sep 17 00:00:00 2001 From: Niko Matsakis Date: Tue, 28 Jan 2025 10:53:03 -0500 Subject: [PATCH 4/5] Update src/stabilization_report_template.md Co-authored-by: Ralf Jung --- src/stabilization_report_template.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/stabilization_report_template.md b/src/stabilization_report_template.md index 194f81fa3..b5d3fc68b 100644 --- a/src/stabilization_report_template.md +++ b/src/stabilization_report_template.md @@ -42,7 +42,7 @@ An example for async closures: https://rustc-dev-guide.rust-lang.org/coroutine-c (Be sure to link to tests demonstrating that these tests are being done.) -### Can users use this feature to introduce undefined behavior? (Describe.) +### 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.) ### What updates are needed to the reference/specification? (link to PRs when they exist) From 2536baab6d3181b1c8e60b2e9dbe454af3077a94 Mon Sep 17 00:00:00 2001 From: Niko Matsakis Date: Tue, 28 Jan 2025 11:01:28 -0500 Subject: [PATCH 5/5] Update src/stabilization_guide.md Co-authored-by: waffle --- src/stabilization_guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/stabilization_guide.md b/src/stabilization_guide.md index 213280cce..f993bcac8 100644 --- a/src/stabilization_guide.md +++ b/src/stabilization_guide.md @@ -52,7 +52,7 @@ The [template][srt] includes a series of questions that aim to surface interconn 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 +## 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.*