]>
Commit | Line | Data |
---|---|---|
532ac7d7 XL |
1 | # Request for stabilization |
2 | ||
6a06907d XL |
3 | **NOTE**: this page is about stabilizing language features. |
4 | For stabilizing *library* features, see [Stabilizing a library feature]. | |
5 | ||
6 | [Stabilizing a library feature]: ./stability.md#stabilizing-a-library-feature | |
7 | ||
532ac7d7 XL |
8 | Once an unstable feature has been well-tested with no outstanding |
9 | concern, anyone may push for its stabilization. It involves the | |
6a06907d | 10 | following steps: |
532ac7d7 | 11 | |
6a06907d | 12 | <!-- toc --> |
532ac7d7 XL |
13 | |
14 | ## Documentation PRs | |
15 | ||
16 | <a name="updating-documentation"></a> | |
17 | ||
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. | |
21 | ||
22 | If there was documentation there, integrating it into the | |
23 | existing documentation is needed. | |
24 | ||
25 | If there wasn't documentation there, it needs to be added. | |
26 | ||
27 | Places that may need updated documentation: | |
28 | ||
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. | |
38 | ||
416331ca XL |
39 | Prepare PRs to update documentation involving this new feature |
40 | for repositories mentioned above. Maintainers of these repositories | |
532ac7d7 XL |
41 | will keep these PRs open until the whole stabilization process |
42 | has completed. Meanwhile, we can proceed to the next step. | |
43 | ||
44 | ## Write a stabilization report | |
45 | ||
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 | |
416331ca | 49 | as expected, along with a list of edge cases that came up |
532ac7d7 XL |
50 | and were considered. This is a minimal "due diligence" that |
51 | we do before stabilizing. | |
52 | ||
53 | The report should contain: | |
54 | ||
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(Examples of such reports can | |
62 | be found in rust-lang/rust#44494 and rust-lang/rust#28237). | |
63 | - The resolutions of any unresolved questions if the stabilization | |
64 | is for an RFC. | |
65 | ||
66 | ## FCP | |
67 | ||
68 | If any member of the team responsible for tracking this | |
69 | feature agrees with stabilizing this feature, they will | |
70 | start the FCP (final-comment-period) process by commenting | |
71 | ||
72 | ```bash | |
73 | @rfcbot fcp merge | |
74 | ``` | |
75 | ||
76 | The rest of the team members will review the proposal. If the final | |
77 | decision is to stabilize, we proceed to do the actual code modification. | |
78 | ||
79 | ## Stabilization PR | |
80 | ||
81 | Once we have decided to stabilize a feature, we need to have | |
82 | a PR that actually makes that stabilization happen. These kinds | |
83 | of PRs are a great way to get involved in Rust, as they take | |
84 | you on a little tour through the source code. | |
85 | ||
86 | Here is a general guide to how to stabilize a feature -- | |
87 | every feature is different, of course, so some features may | |
88 | require steps beyond what this guide talks about. | |
89 | ||
90 | Note: Before we stabilize any feature, it's the rule that it | |
91 | should appear in the documentation. | |
92 | ||
93 | ### Updating the feature-gate listing | |
94 | ||
95 | There is a central listing of feature-gates in | |
6a06907d | 96 | [`compiler/rustc_feature`]. Search for the `declare_features!` |
532ac7d7 XL |
97 | macro. There should be an entry for the feature you are aiming |
98 | to stabilize, something like (this example is taken from | |
99 | [rust-lang/rust#32409]: | |
100 | ||
101 | ```rust,ignore | |
102 | // pub(restricted) visibilities (RFC 1422) | |
103 | (active, pub_restricted, "1.9.0", Some(32409)), | |
104 | ``` | |
105 | ||
106 | The above line should be moved down to the area for "accepted" | |
107 | features, declared below in a separate call to `declare_features!`. | |
108 | When it is done, it should look like: | |
109 | ||
110 | ```rust,ignore | |
111 | // pub(restricted) visibilities (RFC 1422) | |
112 | (accepted, pub_restricted, "1.31.0", Some(32409)), | |
113 | // note that we changed this | |
114 | ``` | |
115 | ||
116 | Note that, the version number is updated to be the version number | |
117 | of the stable release where this feature will appear. This can be | |
118 | found by consulting [the forge](https://forge.rust-lang.org/), which will guide | |
119 | you the next stable release number. You want to add 1 to that, | |
120 | because the code that lands today will become go into beta on that | |
121 | date, and then become stable after that. So, at the time of this | |
122 | writing, the next stable release (i.e. what is currently beta) was | |
123 | 1.30.0, hence I wrote 1.31.0 above. | |
124 | ||
125 | ### Removing existing uses of the feature-gate | |
126 | ||
127 | Next search for the feature string (in this case, `pub_restricted`) | |
128 | in the codebase to find where it appears. Change uses of | |
6a06907d | 129 | `#![feature(XXX)]` from the `std` and any rustc crates to be |
dc9dc135 | 130 | `#![cfg_attr(bootstrap, feature(XXX))]`. This includes the feature-gate |
532ac7d7 XL |
131 | only for stage0, which is built using the current beta (this is |
132 | needed because the feature is still unstable in the current beta). | |
133 | ||
134 | Also, remove those strings from any tests. If there are tests | |
135 | specifically targeting the feature-gate (i.e., testing that the | |
136 | feature-gate is required to use the feature, but nothing else), | |
137 | simply remove the test. | |
138 | ||
139 | ### Do not require the feature-gate to use the feature | |
140 | ||
141 | Most importantly, remove the code which flags an error if the | |
142 | feature-gate is not present (since the feature is now considered | |
143 | stable). If the feature can be detected because it employs some | |
144 | new syntax, then a common place for that code to be is in the | |
6a06907d | 145 | same `compiler/rustc_ast_passes/src/feature_gate.rs`. |
dfeec247 | 146 | For example, you might see code like this: |
532ac7d7 XL |
147 | |
148 | ```rust,ignore | |
149 | gate_feature_post!(&self, pub_restricted, span, | |
150 | "`pub(restricted)` syntax is experimental"); | |
151 | ``` | |
152 | ||
153 | This `gate_feature_post!` macro prints an error if the | |
154 | `pub_restricted` feature is not enabled. It is not needed | |
155 | now that `#[pub_restricted]` is stable. | |
156 | ||
157 | For more subtle features, you may find code like this: | |
158 | ||
159 | ```rust,ignore | |
160 | if self.tcx.sess.features.borrow().pub_restricted { /* XXX */ } | |
161 | ``` | |
162 | ||
163 | This `pub_restricted` field (obviously named after the feature) | |
164 | would ordinarily be false if the feature flag is not present | |
165 | and true if it is. So transform the code to assume that the field | |
166 | is true. In this case, that would mean removing the `if` and | |
167 | leaving just the `/* XXX */`. | |
168 | ||
169 | ```rust,ignore | |
170 | if self.tcx.sess.features.borrow().pub_restricted { /* XXX */ } | |
171 | becomes | |
172 | /* XXX */ | |
173 | ||
174 | if self.tcx.sess.features.borrow().pub_restricted && something { /* XXX */ } | |
175 | becomes | |
176 | if something { /* XXX */ } | |
177 | ``` | |
178 | ||
dfeec247 | 179 | [rust-lang/rust#32409]: https://github.com/rust-lang/rust/issues/32409 |
6a06907d | 180 | [`compiler/rustc_feature`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_feature/index.html |
dfeec247 | 181 | [The Reference]: https://github.com/rust-lang/reference |
532ac7d7 XL |
182 | [The Book]: https://github.com/rust-lang/book |
183 | [Rust by Example]: https://github.com/rust-lang/rust-by-example | |
184 | [`Unstable Book`]: https://doc.rust-lang.org/unstable-book/index.html | |
185 | [`src/doc/unstable-book`]: https://github.com/rust-lang/rust/tree/master/src/doc/unstable-book |