diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 651e2925a..e3c0d50fc 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -53,7 +53,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) diff --git a/src/implementing_new_features.md b/src/implementing_new_features.md index 5d0e875cb..8e9e2e188 100644 --- a/src/implementing_new_features.md +++ b/src/implementing_new_features.md @@ -206,3 +206,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 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 [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) + +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 + +Once the feature is supported by rustc, there is other associated work that needs to be done to give users a polished experience when using all of the tools we ship. + +- Documenting the language feature in the [Rust Reference][reference]. +- 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, 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 +[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 diff --git a/src/stabilization_guide.md b/src/stabilization_guide.md index f875c6874..c220be480 100644 --- a/src/stabilization_guide.md +++ b/src/stabilization_guide.md @@ -43,61 +43,27 @@ 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, 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. + - Quite often, the final stabilized language feature can have significant design deviations from the original RFC text. 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 connections between this feature and lang's subteams (e.g. types, opsem, lang-docs, etc.) and 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). -*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.* +## Stabilization PR for a language feature -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. +*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.* -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. +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 discusses. -Note: Before we stabilize any feature, it's the rule that it -should appear in the documentation. +Note: 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 accepted by the lang-docs team. ### Updating the feature-gate listing @@ -151,8 +117,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 +127,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 +159,27 @@ 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 + +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/compiler`, for implementation robustness. +- `@rust-lang/opsem`, for interactions with unsafe code. +- `@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. + +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 a `rust-lang` organization member, you can ask your assigned reviewer to CC the relevant teams on your behalf. + +## FCP proposed on the PR + +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 +``` + +Once enough team members have reviewed, the PR will move into a "final comment period". After this period, if no new concerns have been raised, the PR can be merged after implementation review in the usual way. diff --git a/src/stabilization_report_template.md b/src/stabilization_report_template.md new file mode 100644 index 000000000..dcab0a057 --- /dev/null +++ b/src/stabilization_report_template.md @@ -0,0 +1,157 @@ +# 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. This helps reviewers to identify potential problems up front. Not all parts of the template will apply to every stabilizations. Put N/A if a question doesn't apply. +> +> Copy the following template after the separator and edit it as Markdown. Replace each *TODO* with answers. + +--- + +## General design + +### What is the RFC for this feature? + +*TODO* + +### Post-RFC changes + +> What user-visible changes have occurred since the RFC was accepted? + +*TODO* + +### Key points + +> What behaviors to be stabilized have been most controversial? Summarize the major arguments on all sides. + +*TODO* + +### Nightly extensions + +> Are there extensions to this feature that remain unstable? How do we know that we are not accidentally committing to those? + +*TODO* + +## Feedback + +### Call for testing + +> Has a "call for testing" been done? If so, what feedback was received? + +*TODO* + +### Nightly use + +> 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* + +## Implementation quality + +### Major parts + +> Summarize the major parts of the implementation and provide links into the code (or to PRs). +> +> An example for async closures: . + +*TODO* + +### Coverage + +> 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* + +### Outstanding bugs + +> What outstanding bugs in the issue tracker involve this feature? Are they stabilization-blocking? + +*TODO* + +### Outstanding FIXMEs + +> What FIXMEs are still in the code for that feature and why is it ok to leave them there? + +*TODO* + +### Contributors + +> Summarize contributors to the feature by name for recognition and assuredness that people involved in the feature agree with stabilization. + +*TODO* + +### Tool changes + +> Which tools need to be adjusted to support this feature. Has this work been done? +> +> Consider rustdoc (both JSON and HTML), clippy, rust-analyzer, rustfmt, rustup, docs.rs. + +*TODO* + +## Type system and execution rules + +### Compile-time checks + +> 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* + +### Sound by default? + +> 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* + +### Breaks the AM? + +> 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* + +### Reference + +> What updates are needed to the Reference? Link to each PR. + +- *TODO* + +## Common interactions + +### Temporaries + +> Does this feature introduce new expressions that can produce temporaries? What are the lifetimes of those temporaries? + +*TODO* + +### Pre-expansion / post-expansion + +> Does this feature raise questions about what should be accepted pre-expansion (e.g. in code covered by `#[cfg(false)]`) versus what should be accepted post-expansion? What decisions were made about this? + +*TODO* + +### SemVer implications + +> Does this feature create any new ways in which library authors must take care to prevent breaking their downstreams when making minor-version releases? Describe these. Are these new hazards "major" or "minor" according to [RFC 1105](https://rust-lang.github.io/rfcs/1105-api-evolution.html)? + +*TODO* + +### Exposing other features + +> Are there any other unstable features whose behavior may be exposed by this feature in any way? What features present the highest risk of that? + +*TODO*