From 5ecc1795c85cea381848954d07355982185a55b8 Mon Sep 17 00:00:00 2001 From: Scott McMurray Date: Sat, 26 Feb 2022 10:40:10 -0800 Subject: [PATCH 1/2] Add a reference to std-dev-guide for stabilizing library feature Also update the "which version" discussion with more details. --- src/stabilization_guide.md | 34 ++++++++++++++++++++++++++-------- 1 file changed, 26 insertions(+), 8 deletions(-) diff --git a/src/stabilization_guide.md b/src/stabilization_guide.md index 850168705..0aca94b16 100644 --- a/src/stabilization_guide.md +++ b/src/stabilization_guide.md @@ -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][std-guide-stabilization] 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 @@ -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`][src-version] when the PR is merged. + +It's worth checking [the version schedule on the Forge][forge-versions] 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][forge-release-process] 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 @@ -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 @@ -184,6 +198,10 @@ if something { /* XXX */ } ``` [rust-lang/rust#32409]: https://github.com/rust-lang/rust/issues/32409 +[std-guide-stabilization]: https://std-dev-guide.rust-lang.org/feature-lifecycle/stabilization.html +[src-version]: https://github.com/rust-lang/rust/blob/master/src/version +[forge-versions]: https://forge.rust-lang.org/#current-release-versions +[forge-release-process]: 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 From 649a3024d282302ddfad793efce1182af23322c7 Mon Sep 17 00:00:00 2001 From: scottmcm Date: Thu, 3 Mar 2022 22:58:58 +0000 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: pierwill <19642016+pierwill@users.noreply.github.com> --- src/stabilization_guide.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/stabilization_guide.md b/src/stabilization_guide.md index 0aca94b16..454cd0f27 100644 --- a/src/stabilization_guide.md +++ b/src/stabilization_guide.md @@ -106,9 +106,9 @@ the value of [the `src/version` file in `master`][src-version] when the PR is me It's worth checking [the version schedule on the Forge][forge-versions] 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. +"Nightly" is two versions higher than the current stable release, +since what's currently in beta will be the next stable release, +and any changes 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][forge-release-process] the stable release,