Skip to content

Commit 6ccb6f0

Browse files
committed
Add a reference to std-dev-guide for stabilizing library feature
Also update the "which version" discussion with more details.
1 parent 24e474c commit 6ccb6f0

File tree

1 file changed

+26
-8
lines changed

1 file changed

+26
-8
lines changed

src/stabilization_guide.md

+26-8
Original file line numberDiff line numberDiff line change
@@ -84,6 +84,9 @@ decision is to stabilize, we proceed to do the actual code modification.
8484

8585
## Stabilization PR
8686

87+
*This is for stabilizing language features. If you are stabilizing a library
88+
feature, see [the stabilization chapter of the std dev guide] instead.*
89+
8790
Once we have decided to stabilize a feature, we need to have
8891
a PR that actually makes that stabilization happen. These kinds
8992
of PRs are a great way to get involved in Rust, as they take
@@ -96,6 +99,24 @@ require steps beyond what this guide talks about.
9699
Note: Before we stabilize any feature, it's the rule that it
97100
should appear in the documentation.
98101

102+
### Determining the stabilization version
103+
104+
The version in which the feature will be stabilized *must* match
105+
the value of [the `src/version` file in `master`] when the PR is merged.
106+
107+
It's worth checking [the version schedule on the Forge] to see whether
108+
changes are coming soon. You'll usually use the version labelled "Nightly".
109+
That's two versions higher than the current stable release,
110+
as what's currently in beta will be the next stable release,
111+
and any change you're making now will be in the one after that.
112+
113+
No PR is merged instantly, so you'll want to be careful around release time.
114+
The version bump happens [the Friday before] the stable release,
115+
not the same time as the release. So if you're opening a PR shortly before then,
116+
be prepared to update the version, or consider just opening it for one version
117+
higher than the current nightly, with a note saying not to merge until
118+
after the upcoming version bump.
119+
99120
### Updating the feature-gate listing
100121

101122
There is a central listing of feature-gates in
@@ -119,14 +140,7 @@ When it is done, it should look like:
119140
// note that we changed this
120141
```
121142

122-
Note that, the version number is updated to be the version number
123-
of the stable release where this feature will appear. This can be
124-
found by consulting [the forge](https://forge.rust-lang.org/), which will guide
125-
you the next stable release number. You want to add 1 to that,
126-
because the code that lands today will become go into beta on that
127-
date, and then become stable after that. So, at the time of this
128-
writing, the next stable release (i.e. what is currently beta) was
129-
1.30.0, hence I wrote 1.31.0 above.
143+
(The version here is the one discussed in the previous section.)
130144

131145
### Removing existing uses of the feature-gate
132146

@@ -184,6 +198,10 @@ if something { /* XXX */ }
184198
```
185199

186200
[rust-lang/rust#32409]: https://github.com/rust-lang/rust/issues/32409
201+
[the stabilization chapter of the std dev guide]: https://std-dev-guide.rust-lang.org/feature-lifecycle/stabilization.html
202+
[the `src/version` file in `master`]: https://github.com/rust-lang/rust/blob/master/src/version
203+
[the version schedule on the Forge]: https://forge.rust-lang.org/#current-release-versions
204+
[the Friday before]: https://forge.rust-lang.org/release/process.html
187205
[`compiler/rustc_feature`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_feature/index.html
188206
[The Reference]: https://github.com/rust-lang/reference
189207
[The Book]: https://github.com/rust-lang/book

0 commit comments

Comments
 (0)