From e4ee951653734f09ef3c6fa8ae86588d71fe6ffa Mon Sep 17 00:00:00 2001 From: Niko Matsakis Date: Thu, 23 Jan 2025 20:14:53 +0000 Subject: [PATCH 01/19] 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 02/19] 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 03/19] 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 04/19] 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 05/19] 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.* From 882699e328b9b64ba148c65b48f44bb47346a2bd Mon Sep 17 00:00:00 2001 From: Jieyou Xu Date: Thu, 19 Jun 2025 17:33:15 +0800 Subject: [PATCH 06/19] Address Call for Testing review feedback --- src/implementing_new_features.md | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/src/implementing_new_features.md b/src/implementing_new_features.md index 4e09e0602..e632838d8 100644 --- a/src/implementing_new_features.md +++ b/src/implementing_new_features.md @@ -207,7 +207,19 @@ 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 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. +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 @@ -223,3 +235,6 @@ Once the feature is supported by rustc, there is other associated work that need 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 From 1bbe99771184b9db5666a3f671171d9834a9dafb Mon Sep 17 00:00:00 2001 From: Jieyou Xu Date: Thu, 19 Jun 2025 17:48:11 +0800 Subject: [PATCH 07/19] Address Affiliated work review feedback --- src/implementing_new_features.md | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/src/implementing_new_features.md b/src/implementing_new_features.md index e632838d8..b11a0e53e 100644 --- a/src/implementing_new_features.md +++ b/src/implementing_new_features.md @@ -223,18 +223,23 @@ Which option to choose might depend on how significant the language change is, t ## 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: +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. -* Extending rustfmt to format any new syntax; -* Extending rust-analyzer; -* Documenting the feature in the Rust reference; -* ... +- 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 From 3f559ff34aa01f18811414390fb071d51ddac4c8 Mon Sep 17 00:00:00 2001 From: Jieyou Xu Date: Thu, 19 Jun 2025 17:56:47 +0800 Subject: [PATCH 08/19] Drop "stabilization is easy" part --- src/stabilization_guide.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/src/stabilization_guide.md b/src/stabilization_guide.md index f993bcac8..04d7d0e5b 100644 --- a/src/stabilization_guide.md +++ b/src/stabilization_guide.md @@ -57,11 +57,6 @@ If you'd like to develop the stabilization report incrementally, we recommend ad *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. From 8152a0dea48590907676a983303541c0b65d72d3 Mon Sep 17 00:00:00 2001 From: Jieyou Xu Date: Thu, 19 Jun 2025 17:58:17 +0800 Subject: [PATCH 09/19] Fix broken feature gate examples --- src/stabilization_guide.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/src/stabilization_guide.md b/src/stabilization_guide.md index 04d7d0e5b..f5fd11e30 100644 --- a/src/stabilization_guide.md +++ b/src/stabilization_guide.md @@ -116,8 +116,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 @@ -127,7 +126,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) From f80902e3aee42e3e57aa13169cbef34a759b77f1 Mon Sep 17 00:00:00 2001 From: Jieyou Xu Date: Thu, 19 Jun 2025 18:04:51 +0800 Subject: [PATCH 10/19] Elaborate on stabilization report summarization aspects --- src/stabilization_guide.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/src/stabilization_guide.md b/src/stabilization_guide.md index f5fd11e30..6c55e88d4 100644 --- a/src/stabilization_guide.md +++ b/src/stabilization_guide.md @@ -44,8 +44,14 @@ has completed. Meanwhile, we can proceed to the next step. ## Write a stabilization report 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. + +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. [srt]: ./stabilization_report_template.md From fa8dce1efba70c22ebdb454f6f38995a87056e3b Mon Sep 17 00:00:00 2001 From: Jieyou Xu Date: Thu, 19 Jun 2025 18:13:45 +0800 Subject: [PATCH 11/19] Recommend waiting a bit for team nominations --- src/stabilization_guide.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/src/stabilization_guide.md b/src/stabilization_guide.md index 6c55e88d4..6a3a32140 100644 --- a/src/stabilization_guide.md +++ b/src/stabilization_guide.md @@ -165,14 +165,16 @@ if something { /* XXX */ } [`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 +## Team nominations -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: +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 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 +* `@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 From 784f90ee2f8a2e98d15e83573b52aad5ed912b67 Mon Sep 17 00:00:00 2001 From: Jieyou Xu Date: Thu, 19 Jun 2025 18:49:13 +0800 Subject: [PATCH 12/19] Make Stabilization Template markdown copy friendly --- src/stabilization_report_template.md | 89 +++++++++++++++++++--------- 1 file changed, 62 insertions(+), 27 deletions(-) diff --git a/src/stabilization_report_template.md b/src/stabilization_report_template.md index b5d3fc68b..e32ae7356 100644 --- a/src/stabilization_report_template.md +++ b/src/stabilization_report_template.md @@ -1,54 +1,89 @@ # 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. +> +> 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? +> ## General design -### What behavior are we committing to that has been controversial? Summarize the major arguments pro/con. +> ### What is the RFC for this feature and what changes have occurred to the user-facing design since the RFC was finalized? -### 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? +> ### What behavior are we committing to that has been controversial? Summarize the major arguments pro/con. -## Implementation quality +*TODO* -### Summarize the major parts of the implementation and provide links into the code (or to PRs) +> ### Are there extensions to this feature that remain unstable? How do we know that we are not accidentally committing to those? -An example for async closures: https://rustc-dev-guide.rust-lang.org/coroutine-closures.html +*TODO* -### Summarize existing test coverage of this feature +> ## Has a Call for Testing period been conducted? If so, what feedback was received? -- 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? +*TODO* -### What outstanding bugs in the issue tracker involve this feature? Are they stabilization-blocking? +> ## Implementation quality -### 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 +> ### Summarize the major parts of the implementation and provide links into the code (or to PRs) +> +> An example for async closures: . -### Which tools need to be adjusted to support this feature. Has this work been done? +*TODO* -*Consider rustdoc, clippy, rust-analyzer, rustfmt, rustup, docs.rs.* +> ### 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? -## Type system and execution rules +*TODO* -### What compilation-time checks are done that are needed to prevent undefined behavior? +> ### What outstanding bugs in the issue tracker involve this feature? Are they stabilization-blocking? -(Be sure to link to tests demonstrating that these tests are being done.) +*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.) +> ### What FIXMEs are still in the code for that feature and why is it ok to leave them there? -### What updates are needed to the reference/specification? (link to PRs when they exist) +*TODO* -## Common interactions +> ### Summarize contributors to the feature by name for recognition and assuredness that people involved in the feature agree with stabilization -### 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? +> ### 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* + +> ### 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* From ef25866b8f4578033c75681658cb4e35da01f82d Mon Sep 17 00:00:00 2001 From: Jieyou Xu Date: Thu, 19 Jun 2025 18:51:06 +0800 Subject: [PATCH 13/19] Register stabilization report template --- src/SUMMARY.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 91c4aeacb..67967da40 100644 --- a/src/SUMMARY.md +++ b/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) From 183107472f115c5c245d935adb58e81c2045b1d8 Mon Sep 17 00:00:00 2001 From: Jieyou Xu Date: Thu, 19 Jun 2025 18:55:58 +0800 Subject: [PATCH 14/19] Drop unfinished sentence --- src/stabilization_guide.md | 1 - 1 file changed, 1 deletion(-) diff --git a/src/stabilization_guide.md b/src/stabilization_guide.md index 6a3a32140..98a6fcf8c 100644 --- a/src/stabilization_guide.md +++ b/src/stabilization_guide.md @@ -56,7 +56,6 @@ The [*Stabilization Template*][srt] includes a series of questions that aim to s [srt]: ./stabilization_report_template.md 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 for a language feature From 5ad366e50d9254e99b3f257ffc58989e10e32d0f Mon Sep 17 00:00:00 2001 From: Jieyou Xu Date: Thu, 19 Jun 2025 18:57:25 +0800 Subject: [PATCH 15/19] Clarify stabilization report template is for language features --- src/stabilization_report_template.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/stabilization_report_template.md b/src/stabilization_report_template.md index e32ae7356..4323e82a4 100644 --- a/src/stabilization_report_template.md +++ b/src/stabilization_report_template.md @@ -1,6 +1,8 @@ # 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. +> **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. From c7e38e9640ad19f10c0fb26360ac9042de1da026 Mon Sep 17 00:00:00 2001 From: Jieyou Xu Date: Thu, 19 Jun 2025 19:07:12 +0800 Subject: [PATCH 16/19] Add test coverage elaboration --- src/stabilization_report_template.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/src/stabilization_report_template.md b/src/stabilization_report_template.md index 4323e82a4..a0e04f5dc 100644 --- a/src/stabilization_report_template.md +++ b/src/stabilization_report_template.md @@ -37,7 +37,11 @@ *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? > - (Positive/negative) Behavioral tests? > - (Positive/negative) Interface tests? (e.g. compiler cli interface) From beb25e1390b14660d32bd7d9e3724a07aacb000f Mon Sep 17 00:00:00 2001 From: Jieyou Xu Date: Thu, 19 Jun 2025 19:08:53 +0800 Subject: [PATCH 17/19] Add UB checks / opt question --- src/stabilization_report_template.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/src/stabilization_report_template.md b/src/stabilization_report_template.md index a0e04f5dc..75b84b0ef 100644 --- a/src/stabilization_report_template.md +++ b/src/stabilization_report_template.md @@ -76,7 +76,11 @@ *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.) +> ### 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* From 6fe303f4310176f5c87a0f686ea9ff8915f3ae35 Mon Sep 17 00:00:00 2001 From: Jieyou Xu Date: Thu, 19 Jun 2025 19:12:38 +0800 Subject: [PATCH 18/19] Amend test coverage explanation --- src/stabilization_report_template.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/src/stabilization_report_template.md b/src/stabilization_report_template.md index 75b84b0ef..3a6c8e177 100644 --- a/src/stabilization_report_template.md +++ b/src/stabilization_report_template.md @@ -43,10 +43,14 @@ > 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? -> - (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? +> - 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* From eb4eba8ab2057ef2e56666d18c75bb83dc6da98d Mon Sep 17 00:00:00 2001 From: Jieyou Xu Date: Thu, 19 Jun 2025 19:15:06 +0800 Subject: [PATCH 19/19] Mention OSS nightly users --- src/stabilization_report_template.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/stabilization_report_template.md b/src/stabilization_report_template.md index 3a6c8e177..90437ee7a 100644 --- a/src/stabilization_report_template.md +++ b/src/stabilization_report_template.md @@ -23,6 +23,8 @@ *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 for `#![feature(FEATURE_NAME)]` and had `N` results". *TODO*