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

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