src/doc/rustc-dev-guide/src/stabilization_guide.md

   1 # Request for stabilization
   2
   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
   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:
  11
  12 <!-- toc -->
  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
  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.
  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
  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:
  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
  96 [`compiler/rustc_feature`]. Search for the `declare_features!`
  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
 129 `#![feature(XXX)]` from the `std` and any rustc crates to be
 130 `#![cfg_attr(bootstrap, feature(XXX))]`. This includes the feature-gate
 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
 145 same `compiler/rustc_ast_passes/src/feature_gate.rs`.
 146 For example, you might see code like this:
 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
 179 [rust-lang/rust#32409]: https://github.com/rust-lang/rust/issues/32409
 180 [`compiler/rustc_feature`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_feature/index.html
 181 [The Reference]: https://github.com/rust-lang/reference
 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