You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
**NOTE**: this page is about stabilizing *language* features.
4
-
For stabilizing *library* features, see [Stabilizing a library feature].
3
+
**NOTE**: This page is about stabilizing *language* features. For stabilizing *library* features, see [Stabilizing a library feature].
5
4
6
5
[Stabilizing a library feature]: ./stability.md#stabilizing-a-library-feature
7
6
8
-
Once an unstable feature has been well-tested with no outstanding
9
-
concern, anyone may push for its stabilization. It involves the
10
-
following steps:
7
+
Once an unstable feature has been well-tested with no outstanding concerns, anyone may push for its stabilization, though involving the people who have worked on it is prudent. Follow these steps:
11
8
12
9
<!-- toc -->
13
10
14
-
## Documentation PRs
11
+
## Write an RFC, if needed
15
12
16
-
<aid="updating-documentation"></a>
13
+
If the feature was part of a [lang experiment], the lang team generally will want to first accept an RFC before stabilization.
17
14
18
-
If any documentation for this feature exists, it should be
19
-
in the [`Unstable Book`], located at [`src/doc/unstable-book`].
20
-
If it exists, the page for the feature gate should be removed.
If there was documentation there, integrating it into the
23
-
existing documentation is needed.
19
+
<aid="updating-documentation"></a>
24
20
25
-
If there wasn't documentation there, it needs to be added.
21
+
The feature might be documented in the [`Unstable Book`], located at [`src/doc/unstable-book`]. Remove the page for the feature gate if it exists. Integrate any useful parts of that documentation in other places.
26
22
27
-
Places that may need updated documentation:
23
+
Places that may need updated documentation include:
28
24
29
-
-[The Reference]: This must be updated, in full detail.
30
-
-[The Book]: This may or may not need updating, depends.
31
-
If you're not sure, please open an issue on this repository
32
-
and it can be discussed.
33
-
- standard library documentation: As needed. Language features
34
-
often don't need this, but if it's a feature that changes
35
-
how good examples are written, such as when `?` was added
36
-
to the language, updating examples is important.
37
-
-[Rust by Example]: As needed.
25
+
-[The Reference]: This must be updated, in full detail, and a member of the lang-docs team must review and approve the PR before the stabilization can be merged.
26
+
-[The Book]: This is updated as needed. If you're not sure, please open an issue on this repository and it can be discussed.
27
+
- Standard library documentation: This is updated as needed. Language features often don't need this, but if it's a feature that changes how idiomatic examples are written, such as when `?` was added to the language, updating these in the library documentation is important. Review also the keyword documentation and ABI documentation in the standard library, as these sometimes needs updates for language changes.
28
+
-[Rust by Example]: This is updated as needed.
38
29
39
-
Prepare PRs to update documentation involving this new feature
40
-
for repositories mentioned above. Maintainers of these repositories
41
-
will keep these PRs open until the whole stabilization process
42
-
has completed. Meanwhile, we can proceed to the next step.
30
+
Prepare PRs to update documentation involving this new feature for the repositories mentioned above. Maintainers of these repositories will keep these PRs open until the whole stabilization process has completed. Meanwhile, we can proceed to the next step.
43
31
44
32
## Write a stabilization report
45
33
46
-
Find the tracking issue of the feature, and create a short
47
-
stabilization report. Essentially this would be a brief summary
48
-
of the feature plus some links to test cases showing it works
49
-
as expected, along with a list of edge cases that came up
50
-
and were considered. This is a minimal "due diligence" that
51
-
we do before stabilizing.
52
-
53
-
The report should contain:
34
+
Author a stabilization report using the [template found in this repository][srt].
54
35
55
-
- A summary, showing examples (e.g. code snippets) what is
56
-
enabled by this feature.
57
-
- Links to test cases in our test suite regarding this feature
58
-
and describe the feature's behavior on encountering edge cases.
59
-
- Links to the documentations (the PRs we have made in the
60
-
previous steps).
61
-
- Any other relevant information.
62
-
- The resolutions of any unresolved questions if the stabilization
63
-
is for an RFC.
36
+
The stabilization reports summarizes:
64
37
65
-
Examples of stabilization reports can be found in
66
-
[rust-lang/rust#44494][report1] and [rust-lang/rust#28237][report2] (these links
67
-
will bring you directly to the comment containing the stabilization report).
38
+
- 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.
39
+
- Often, the final stabilized language feature has significant design deviations from the original RFC. That's OK, but these deviations must be highlighted and explained carefully.
40
+
- 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.
71
43
72
-
## FCP
44
+
[srt]: ./stabilization_report_template.md
73
45
74
-
If any member of the team responsible for tracking this
75
-
feature agrees with stabilizing this feature, they will
76
-
start the FCP (final-comment-period) process by commenting
77
-
78
-
```text
79
-
@rfcbot fcp merge
80
-
```
81
-
82
-
The rest of the team members will review the proposal. If the final
83
-
decision is to stabilize, we proceed to do the actual code modification.
46
+
The stabilization report is typically posted as the main comment on the stabilization PR (see the next section).
84
47
85
48
## Stabilization PR
86
49
87
-
*This is for stabilizing language features. If you are stabilizing a library
88
-
feature, see [the stabilization chapter of the std dev guide][std-guide-stabilization] instead.*
89
-
90
-
Once we have decided to stabilize a feature, we need to have
91
-
a PR that actually makes that stabilization happen. These kinds
92
-
of PRs are a great way to get involved in Rust, as they take
93
-
you on a little tour through the source code.
50
+
Every feature is different, and some may require steps beyond what this guide discusses.
94
51
95
-
Here is a general guide to how to stabilize a feature --
96
-
every feature is different, of course, so some features may
97
-
require steps beyond what this guide talks about.
98
-
99
-
Note: Before we stabilize any feature, it's the rule that it
100
-
should appear in the documentation.
52
+
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 approved by the lang-docs team.
101
53
102
54
### Updating the feature-gate listing
103
55
104
-
There is a central listing of unstable feature-gates in
105
-
[`compiler/rustc_feature/src/unstable.rs`]. Search for the `declare_features!`
106
-
macro. There should be an entry for the feature you are aiming
107
-
to stabilize, something like (this example is taken from
108
-
[rust-lang/rust#32409]:
56
+
There is a central listing of unstable feature-gates in [`compiler/rustc_feature/src/unstable.rs`]. Search for the `declare_features!` macro. There should be an entry for the feature you are aiming to stabilize, something like (this example is taken from [rust-lang/rust#32409]:
The above line should be moved to [`compiler/rustc_feature/src/accepted.rs`].
116
-
Entries in the `declare_features!` call are sorted, so find the correct place.
117
-
When it is done, it should look like:
63
+
The above line should be moved to [`compiler/rustc_feature/src/accepted.rs`]. Entries in the `declare_features!` call are sorted, so find the correct place. When it is done, it should look like:
(Even though you will encounter version numbers in the file of past changes,
126
-
you should not put the rustc version you expect your stabilization to happen in,
127
-
but instead `CURRENT_RUSTC_VERSION`)
71
+
(Even though you will encounter version numbers in the file of past changes, you should not put the rustc version you expect your stabilization to happen in, but instead use `CURRENT_RUSTC_VERSION`.)
128
72
129
73
### Removing existing uses of the feature-gate
130
74
131
-
Next search for the feature string (in this case, `pub_restricted`)
132
-
in the codebase to find where it appears. Change uses of
133
-
`#![feature(XXX)]` from the `std` and any rustc crates (this includes test folders
134
-
under `library/` and `compiler/` but not the toplevel `tests/` one) to be
135
-
`#![cfg_attr(bootstrap, feature(XXX))]`. This includes the feature-gate
136
-
only for stage0, which is built using the current beta (this is
137
-
needed because the feature is still unstable in the current beta).
75
+
Next, search for the feature string (in this case, `pub_restricted`) in the codebase to find where it appears. Change uses of `#![feature(XXX)]` from the `std` and any rustc crates (this includes test folders under `library/` and `compiler/` but not the toplevel `tests/` one) to be `#![cfg_attr(bootstrap, feature(XXX))]`. This includes the feature-gate only for stage0, which is built using the current beta (this is needed because the feature is still unstable in the current beta).
138
76
139
-
Also, remove those strings from any tests (e.g. under `tests/`). If there are tests
140
-
specifically targeting the feature-gate (i.e., testing that the
141
-
feature-gate is required to use the feature, but nothing else),
142
-
simply remove the test.
77
+
Also, remove those strings from any tests (e.g. under `tests/`). If there are tests specifically targeting the feature-gate (i.e., testing that the feature-gate is required to use the feature, but nothing else), simply remove the test.
143
78
144
79
### Do not require the feature-gate to use the feature
145
80
146
-
Most importantly, remove the code which flags an error if the
147
-
feature-gate is not present (since the feature is now considered
148
-
stable). If the feature can be detected because it employs some
149
-
new syntax, then a common place for that code to be is in the
150
-
same `compiler/rustc_ast_passes/src/feature_gate.rs`.
151
-
For example, you might see code like this:
81
+
Most importantly, remove the code which flags an error if the feature-gate is not present (since the feature is now considered stable). If the feature can be detected because it employs some new syntax, then a common place for that code to be is in `compiler/rustc_ast_passes/src/feature_gate.rs`. For example, you might see code like this:
152
82
153
83
```rust,ignore
154
-
gate_feature_post!(&self, pub_restricted, span,
155
-
"`pub(restricted)` syntax is experimental");
84
+
gate_all!(pub_restricted, "`pub(restricted)` syntax is experimental");
156
85
```
157
86
158
-
This `gate_feature_post!` macro prints an error if the
159
-
`pub_restricted` feature is not enabled. It is not needed
160
-
now that `#[pub_restricted]` is stable.
87
+
This `gate_feature_post!` macro prints an error if the `pub_restricted` feature is not enabled. It is not needed now that `#[pub_restricted]` is stable.
161
88
162
89
For more subtle features, you may find code like this:
163
90
164
91
```rust,ignore
165
-
if self.tcx.sess.features.borrow().pub_restricted { /* XXX */ }
92
+
if self.tcx.features().async_fn_in_dyn_trait() { /* XXX */ }
166
93
```
167
94
168
-
This `pub_restricted` field (obviously named after the feature)
169
-
would ordinarily be false if the feature flag is not present
170
-
and true if it is. So transform the code to assume that the field
171
-
is true. In this case, that would mean removing the `if` and
172
-
leaving just the `/* XXX */`.
95
+
This `pub_restricted` field (named after the feature) would ordinarily be false if the feature flag is not present and true if it is. So transform the code to assume that the field is true. In this case, that would mean removing the `if` and leaving just the `/* XXX */`.
173
96
174
97
```rust,ignore
175
98
if self.tcx.sess.features.borrow().pub_restricted { /* XXX */ }
@@ -194,3 +117,40 @@ if something { /* XXX */ }
194
117
[Rust by Example]: https://github.com/rust-lang/rust-by-example
When opening the stabilization PR, CC the lang team and its advisors (`@rust-lang/lang @rust-lang/lang-advisors`) and any other teams to whom the feature is relevant, e.g.:
124
+
125
+
-`@rust-lang/types`, for type system interactions.
126
+
-`@rust-lang/opsem`, for interactions with unsafe code.
127
+
-`@rust-lang/compiler`, for implementation robustness.
128
+
-`@rust-lang/libs-api`, for changes to the standard library API or its guarantees.
129
+
-`@rust-lang/lang-docs`, for questions about how this should be documented in the Reference.
130
+
131
+
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.
132
+
133
+
If you are not a `rust-lang` organization member, you can ask your assigned reviewer to CC the relevant teams on your behalf.
134
+
135
+
## Propose FCP on the PR
136
+
137
+
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:
138
+
139
+
```text
140
+
@rfcbot fcp merge
141
+
```
142
+
143
+
Once enough team members have reviewed, the PR will move into a "final comment period" (FCP). If no new concerns are raised, this period will complete and the PR can be merged after implementation review in the usual way.
144
+
145
+
## Reviewing and merging stabilizations
146
+
147
+
On a stabilization, before giving it the `r+`, ensure that the PR:
148
+
149
+
- Matches what the team proposed for stabilization and what is documented in the Reference PR.
150
+
- Includes any changes the team decided to request along the way in order to resolve or avoid concerns.
151
+
- Is otherwise exactly what is described in the stabilization report and in any relevant RFCs or prior lang FCPs.
152
+
- Does not expose on stable behaviors other than those specified, accepted for stabilization, and documented in the Reference.
153
+
- Has sufficient tests to convincingly demonstrate these things.
154
+
- Is accompanied by a PR to the Reference than has been reviewed and approved by a member of lang-docs.
155
+
156
+
In particular, when reviewing the PR, keep an eye out for any user-visible details that the lang team failed to consider and specify. If you find one, describe it and nominate the PR for the lang team.
0 commit comments