Skip to content

Commit

Permalink
Add a reference to std-dev-guide for stabilizing library feature
Browse files Browse the repository at this point in the history
Also update the "which version" discussion with more details.
  • Loading branch information
scottmcm committed Feb 26, 2022
1 parent 24e474c commit 6ccb6f0
Showing 1 changed file with 26 additions and 8 deletions.
34 changes: 26 additions & 8 deletions src/stabilization_guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -84,6 +84,9 @@ decision is to stabilize, we proceed to do the actual code modification.

## Stabilization PR

*This is for stabilizing language features. If you are stabilizing a library
feature, see [the stabilization chapter of the std dev guide] instead.*

Once we have decided to stabilize a feature, we need to have
a PR that actually makes that stabilization happen. These kinds
of PRs are a great way to get involved in Rust, as they take
Expand All @@ -96,6 +99,24 @@ require steps beyond what this guide talks about.
Note: Before we stabilize any feature, it's the rule that it
should appear in the documentation.

### Determining the stabilization version

The version in which the feature will be stabilized *must* match
the value of [the `src/version` file in `master`] when the PR is merged.

It's worth checking [the version schedule on the Forge] to see whether
changes are coming soon. You'll usually use the version labelled "Nightly".
That's two versions higher than the current stable release,
as what's currently in beta will be the next stable release,
and any change you're making now will be in the one after that.

No PR is merged instantly, so you'll want to be careful around release time.
The version bump happens [the Friday before] the stable release,
not the same time as the release. So if you're opening a PR shortly before then,
be prepared to update the version, or consider just opening it for one version
higher than the current nightly, with a note saying not to merge until
after the upcoming version bump.

### Updating the feature-gate listing

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

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

### Removing existing uses of the feature-gate

Expand Down Expand Up @@ -184,6 +198,10 @@ if something { /* XXX */ }
```

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

0 comments on commit 6ccb6f0

Please sign in to comment.