From fb852e98770f1b3c71c8bfd78f32c1bf9f9051f7 Mon Sep 17 00:00:00 2001 From: Jane Lusby Date: Thu, 3 Mar 2022 14:54:10 -0800 Subject: [PATCH 01/17] Update stabilization documentation --- src/feature-lifecycle/stabilization.md | 27 +++++++++++++++++++++----- 1 file changed, 22 insertions(+), 5 deletions(-) diff --git a/src/feature-lifecycle/stabilization.md b/src/feature-lifecycle/stabilization.md index f361efd..49b08e5 100644 --- a/src/feature-lifecycle/stabilization.md +++ b/src/feature-lifecycle/stabilization.md @@ -1,6 +1,7 @@ # Stabilizing features -**Status:** Stub +**Status:** Current +**Last Updated:** 2022/03/03 Feature stabilization involves adding `#[stable]` attributes. They may be introduced alongside new trait impls or replace existing `#[unstable]` attributes. @@ -12,11 +13,11 @@ Check to see if a FCP has completed first. If not, either ping `@rust-lang/libs` This will save you from opening a stabilization PR and having it need regular rebasing while the FCP process runs its course. -## Writing a stabilization PR +## Partial Stabilizations + +When you only wish to stabilize a subset of an existing feature your first step should be to split the feature into multiple features, each with their own tracking issues. -- Replace any `#[unstable]` attributes for the given feature with stable ones. The value of the `since` field is usually the current `nightly` version. -- Remove any `#![feature()]` attributes that were previously required. -- Submit a PR with a stabilization report. +You can see an example of partially stabilizing a feature with tracking issues [#71146](https://github.com/rust-lang/rust/issues/71146) and [XXXXX]() with FCP and the associated implementation PR [XXXXX](). ## When there's `const` involved @@ -25,3 +26,19 @@ Const functions can be stabilized in a PR that replaces `#[rustc_const_unstable] Check whether the function internally depends on other unstable `const` functions through `#[allow_internal_unstable]` attributes and consider how the function could be implemented if its internally unstable calls were removed. See the _Stability attributes_ page for more details on `#[allow_internal_unstable]`. Where `unsafe` and `const` is involved, e.g., for operations which are "unconst", that the const safety argument for the usage also be documented. That is, a `const fn` has additional determinism (e.g. run-time/compile-time results must correspond and the function's output only depends on its inputs...) restrictions that must be preserved, and those should be argued when `unsafe` is used. + +## Writing a stabilization PR + +To stabilize a feature, follow these steps: + +0. (Optional) For partial stabilizations, create a new tracking issue for either the subset being stabilized or the subset being left unstable as preferred. If you're unsure which way is best ask a libs-api team member. +0. Ask a **@rust-lang/libs-api** member to start an FCP on the tracking issue and wait for the FCP to complete (with `disposition-merge`). +0. Change `#[unstable(...)]` to `#[stable(since = "version")]`. `version` should be the *current nightly*, i.e. stable+2. You can see which version is the current nightly [on Forge](https://forge.rust-lang.org/#current-release-versions). +0. Remove `#![feature(...)]` from any test or doc-test for this API. If the feature is used in the compiler or tools, remove it from there as well. +0. If applicable, change `#[rustc_const_unstable(...)]` to `#[rustc_const_stable(since = "version")]`. +0. Open a PR against `rust-lang/rust`. + - Add the appropriate labels: `@rustbot modify labels: +T-libs-api`. + - Link to the tracking issue and say "Closes #XXXXX". + +You can see an example of stabilizing a feature with [tracking issue #81656 with FCP](https://github.com/rust-lang/rust/issues/81656) and the associated [implementation PR #84642](https://github.com/rust-lang/rust/pull/84642). + From 4e2218857a21f1c78bb956180aa957445b5d3e47 Mon Sep 17 00:00:00 2001 From: Jane Lusby Date: Thu, 3 Mar 2022 15:46:16 -0800 Subject: [PATCH 02/17] add detailed section that scottmcm wrote for rustc dev guide --- src/feature-lifecycle/stabilization.md | 57 ++++++++++++++++++++++++-- 1 file changed, 54 insertions(+), 3 deletions(-) diff --git a/src/feature-lifecycle/stabilization.md b/src/feature-lifecycle/stabilization.md index 49b08e5..fcdec9f 100644 --- a/src/feature-lifecycle/stabilization.md +++ b/src/feature-lifecycle/stabilization.md @@ -15,7 +15,7 @@ This will save you from opening a stabilization PR and having it need regular re ## Partial Stabilizations -When you only wish to stabilize a subset of an existing feature your first step should be to split the feature into multiple features, each with their own tracking issues. +When you only wish to stabilize a subset of an existing feature your first step should be to split the feature into multiple features, each with their own tracking issues. How you split up that feature is situational and depends on the specific feature and how you're splitting it up, so in some cases you may want to create a new tracking issue for the portion being stabilized, and in other situations you may want to use the new tracking issue to track the portion being left unstable. If you're unsure how to split up the issue you can always ask a libs-api team member for guidance in the original tracking issue or in the [libs team zulip](https://rust-lang.zulipchat.com/#narrow/stream/219381-t-libs). You can see an example of partially stabilizing a feature with tracking issues [#71146](https://github.com/rust-lang/rust/issues/71146) and [XXXXX]() with FCP and the associated implementation PR [XXXXX](). @@ -27,11 +27,62 @@ Check whether the function internally depends on other unstable `const` function Where `unsafe` and `const` is involved, e.g., for operations which are "unconst", that the const safety argument for the usage also be documented. That is, a `const fn` has additional determinism (e.g. run-time/compile-time results must correspond and the function's output only depends on its inputs...) restrictions that must be preserved, and those should be argued when `unsafe` is used. -## Writing a stabilization PR +## Stabilization PR for Library Features + +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're typically small -- just updating attributes. + +Here is a general guide to how to stabilize a feature -- every feature is different, of course, so some features may require steps beyond what this guide talks about. + +### Update the stability attributes on the items + +Library items are marked unstable via the `#[unstable]` attribute, like this: + +```rust,ignore +#[unstable(feature = "total_cmp", issue = "72599")] +pub fn total_cmp(&self, other: &Self) -> crate::cmp::Ordering { ... } +``` + +You'll need to change that to a `#[stable]` attribute with a version: + +```rust,ignore +#[stable(feature = "total_cmp", since = "1.61.0")] +``` + +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/#current-release-versions). Specifically, you'll want to 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. + +### Remove feature gates from doctests + +All the doctests on the items being stabilized will be enabling the unstable feature, so now that it's stable those attributes are no longer needed and should be removed. + +`````diff + /// # Examples + /// + /// ``` +-/// #![feature(total_cmp)] +-/// + /// assert_eq!(0.0_f32.total_cmp(&-0.0), std::cmp::Ordering::Greater); + /// ``` +````` + +The most obvious place to find these is on the item itself, but it's worth searching the whole library. Often you'll find other unstable methods that were also using it in their tests. + +### Remove feature gates from the compiler + +The compiler builds with nightly features allowed, so you may find uses of the feature there as well. These also need to be removed. + +```diff + #![feature(once_cell)] + #![feature(never_type)] +-#![feature(total_cmp)] + #![feature(trusted_step)] + #![feature(try_blocks)] +``` + +## Stabilization PR Checklist To stabilize a feature, follow these steps: -0. (Optional) For partial stabilizations, create a new tracking issue for either the subset being stabilized or the subset being left unstable as preferred. If you're unsure which way is best ask a libs-api team member. +0. (Optional) For partial stabilizations, create a new tracking issue for either the subset being stabilized or the subset being left unstable, whichever makes the most sense based on the situation. 0. Ask a **@rust-lang/libs-api** member to start an FCP on the tracking issue and wait for the FCP to complete (with `disposition-merge`). 0. Change `#[unstable(...)]` to `#[stable(since = "version")]`. `version` should be the *current nightly*, i.e. stable+2. You can see which version is the current nightly [on Forge](https://forge.rust-lang.org/#current-release-versions). 0. Remove `#![feature(...)]` from any test or doc-test for this API. If the feature is used in the compiler or tools, remove it from there as well. From 53428b028d28e8e0318f3ee6ab4a582108005ab8 Mon Sep 17 00:00:00 2001 From: Jane Lusby Date: Thu, 10 Mar 2022 16:30:52 -0800 Subject: [PATCH 03/17] add section on stabilization reports --- src/feature-lifecycle/stabilization.md | 27 ++++++++++++++++++++++++-- 1 file changed, 25 insertions(+), 2 deletions(-) diff --git a/src/feature-lifecycle/stabilization.md b/src/feature-lifecycle/stabilization.md index fcdec9f..fa2b3c7 100644 --- a/src/feature-lifecycle/stabilization.md +++ b/src/feature-lifecycle/stabilization.md @@ -1,11 +1,33 @@ # Stabilizing features **Status:** Current -**Last Updated:** 2022/03/03 +**Last Updated:** 2022/03/10 Feature stabilization involves adding `#[stable]` attributes. They may be introduced alongside new trait impls or replace existing `#[unstable]` attributes. -Stabilization goes through the Libs FCP process, which occurs on the [tracking issue](./tracking-issues.md) for the feature. +Stabilization goes through the Libs FCP[^1] process, which occurs on the [tracking issue](./tracking-issues.md) for the feature. + +## When is an FCP appropriate? + +Once an unstable feature has been well-tested with no outstanding concerns, +anyone may push for it's stabilization. If you're unsure if a feature is ready +for stabilization the first step should be to ask in the relevant tracking +issue and get assistance from other participants in that discussion. In some +cases the tracking issue may not have many other active participants, so if +you're ever having trouble getting any feedback please ping one of the [libs +team +reviewers](https://github.com/rust-lang/highfive/blob/master/highfive/configs/rust-lang/rust.json) +directly to request assistance. + +## Stabilization Report + +Once a feature is ready for stabilization the first step of the FCP process is writing a stabilization report. Stabilization reports consist of three primary sections, a implementation history, an API summary, and an experience report. + +The **Implementation History** section should summarize the initial discussion during the implementation PR, every change that has been made to the feature since the initial implementation, all issues that were raised during the lifetime of the feature, and how they were resolved. + +The **API Summary** section should include a precise description of what APIs are being introduced to the standard libraries. The libs team maintains a tool for this called [`cargo unstable-api`](https://github.com/rust-lang/libs-team/tree/main/tools/unstable-api) that can be used to generate these API summaries in some cases. *Note* the current implementation of this tool is fragile and does not work in all cases. We hope to have a more permanent version of this tool in the future that is built ontop of either rustdoc or rustc's own APIs. + +The **Experience Report** section should include links to projects that use the feature being stabilized, or when applicable, projects that use crates that export the same API and describe the experience of using the feature in question. ## Before writing a PR to stabilize a feature @@ -93,3 +115,4 @@ To stabilize a feature, follow these steps: You can see an example of stabilizing a feature with [tracking issue #81656 with FCP](https://github.com/rust-lang/rust/issues/81656) and the associated [implementation PR #84642](https://github.com/rust-lang/rust/pull/84642). +[^1]: FCP stands for final comment period From fda8cacf6bbcd82f56420fda92bb8372d110aa6f Mon Sep 17 00:00:00 2001 From: Jane Lusby Date: Thu, 10 Mar 2022 16:44:08 -0800 Subject: [PATCH 04/17] fix formatting --- src/feature-lifecycle/stabilization.md | 10 +--------- 1 file changed, 1 insertion(+), 9 deletions(-) diff --git a/src/feature-lifecycle/stabilization.md b/src/feature-lifecycle/stabilization.md index fa2b3c7..344208b 100644 --- a/src/feature-lifecycle/stabilization.md +++ b/src/feature-lifecycle/stabilization.md @@ -9,15 +9,7 @@ Stabilization goes through the Libs FCP[^1] process, which occurs on the [tracki ## When is an FCP appropriate? -Once an unstable feature has been well-tested with no outstanding concerns, -anyone may push for it's stabilization. If you're unsure if a feature is ready -for stabilization the first step should be to ask in the relevant tracking -issue and get assistance from other participants in that discussion. In some -cases the tracking issue may not have many other active participants, so if -you're ever having trouble getting any feedback please ping one of the [libs -team -reviewers](https://github.com/rust-lang/highfive/blob/master/highfive/configs/rust-lang/rust.json) -directly to request assistance. +Once an unstable feature has been well-tested with no outstanding concerns, anyone may push for it's stabilization. If you're unsure if a feature is ready for stabilization the first step should be to ask in the relevant tracking issue and get assistance from other participants in that discussion. In some cases the tracking issue may not have many other active participants, so if you're ever having trouble getting any feedback please ping one of the [libs team reviewers](https://github.com/rust-lang/highfive/blob/master/highfive/configs/rust-lang/rust.json) directly to request assistance. ## Stabilization Report From 9a1909cbfab4d1743f1cc5a708562f99d946bada Mon Sep 17 00:00:00 2001 From: Jane Lusby Date: Thu, 10 Mar 2022 16:47:47 -0800 Subject: [PATCH 05/17] specify exactly how to handle a partial stabilization --- src/feature-lifecycle/stabilization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/feature-lifecycle/stabilization.md b/src/feature-lifecycle/stabilization.md index 344208b..549eb7a 100644 --- a/src/feature-lifecycle/stabilization.md +++ b/src/feature-lifecycle/stabilization.md @@ -29,7 +29,7 @@ This will save you from opening a stabilization PR and having it need regular re ## Partial Stabilizations -When you only wish to stabilize a subset of an existing feature your first step should be to split the feature into multiple features, each with their own tracking issues. How you split up that feature is situational and depends on the specific feature and how you're splitting it up, so in some cases you may want to create a new tracking issue for the portion being stabilized, and in other situations you may want to use the new tracking issue to track the portion being left unstable. If you're unsure how to split up the issue you can always ask a libs-api team member for guidance in the original tracking issue or in the [libs team zulip](https://rust-lang.zulipchat.com/#narrow/stream/219381-t-libs). +When you only wish to stabilize a subset of an existing feature your first step should be to split the feature into multiple features, each with their own tracking issues. When you're splitting up the feature, you should always introduce a new feature name for the portion being stabilized and leave the existing feature for the portions left unstable, that way existing users of that feature are not left in a broken state. You can see an example of partially stabilizing a feature with tracking issues [#71146](https://github.com/rust-lang/rust/issues/71146) and [XXXXX]() with FCP and the associated implementation PR [XXXXX](). From 927f807e36da12506fa236745669ead537bff369 Mon Sep 17 00:00:00 2001 From: Jane Lusby Date: Fri, 11 Mar 2022 11:48:09 -0800 Subject: [PATCH 06/17] fix inconsistencies with docs for partial stabilization --- src/feature-lifecycle/stabilization.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/src/feature-lifecycle/stabilization.md b/src/feature-lifecycle/stabilization.md index 549eb7a..6dd7bba 100644 --- a/src/feature-lifecycle/stabilization.md +++ b/src/feature-lifecycle/stabilization.md @@ -9,7 +9,9 @@ Stabilization goes through the Libs FCP[^1] process, which occurs on the [tracki ## When is an FCP appropriate? -Once an unstable feature has been well-tested with no outstanding concerns, anyone may push for it's stabilization. If you're unsure if a feature is ready for stabilization the first step should be to ask in the relevant tracking issue and get assistance from other participants in that discussion. In some cases the tracking issue may not have many other active participants, so if you're ever having trouble getting any feedback please ping one of the [libs team reviewers](https://github.com/rust-lang/highfive/blob/master/highfive/configs/rust-lang/rust.json) directly to request assistance. +Once an unstable feature has been well-tested with no outstanding concerns, anyone may push for it's stabilization. + +If you're unsure if a feature is ready for stabilization the first step should be to ask in the relevant tracking issue and get assistance from other participants in that discussion. In some cases the tracking issue may not have many other active participants, so if you're ever having trouble getting any feedback please ping one of the [libs team reviewers](https://github.com/rust-lang/highfive/blob/master/highfive/configs/rust-lang/rust.json) directly to request assistance. ## Stabilization Report @@ -31,7 +33,9 @@ This will save you from opening a stabilization PR and having it need regular re When you only wish to stabilize a subset of an existing feature your first step should be to split the feature into multiple features, each with their own tracking issues. When you're splitting up the feature, you should always introduce a new feature name for the portion being stabilized and leave the existing feature for the portions left unstable, that way existing users of that feature are not left in a broken state. -You can see an example of partially stabilizing a feature with tracking issues [#71146](https://github.com/rust-lang/rust/issues/71146) and [XXXXX]() with FCP and the associated implementation PR [XXXXX](). +You can see an example of partially stabilizing a feature with tracking issue [#71146](https://github.com/rust-lang/rust/issues/71146) and partial stabilization + tracking PR [#94640](https://github.com/rust-lang/rust/pull/94640). + +If you're unsure if a feature is ready for partial stabilization the first step should be to ask in the relevant tracking issue and get assistance from other participants in that discussion. In some cases the tracking issue may not have many other active participants, so if you're ever having trouble getting any feedback please ping one of the [libs team reviewers](https://github.com/rust-lang/highfive/blob/master/highfive/configs/rust-lang/rust.json) directly to request assistance. ## When there's `const` involved @@ -96,7 +100,7 @@ The compiler builds with nightly features allowed, so you may find uses of the f To stabilize a feature, follow these steps: -0. (Optional) For partial stabilizations, create a new tracking issue for either the subset being stabilized or the subset being left unstable, whichever makes the most sense based on the situation. +0. (Optional) For partial stabilizations, create a new partial stabilization + tracking PR for the subset of the issue being stabilized under a newly introduced feature name. 0. Ask a **@rust-lang/libs-api** member to start an FCP on the tracking issue and wait for the FCP to complete (with `disposition-merge`). 0. Change `#[unstable(...)]` to `#[stable(since = "version")]`. `version` should be the *current nightly*, i.e. stable+2. You can see which version is the current nightly [on Forge](https://forge.rust-lang.org/#current-release-versions). 0. Remove `#![feature(...)]` from any test or doc-test for this API. If the feature is used in the compiler or tools, remove it from there as well. @@ -108,3 +112,4 @@ To stabilize a feature, follow these steps: You can see an example of stabilizing a feature with [tracking issue #81656 with FCP](https://github.com/rust-lang/rust/issues/81656) and the associated [implementation PR #84642](https://github.com/rust-lang/rust/pull/84642). [^1]: FCP stands for final comment period + From af2581b7de8342e2ac15f1514c532597580a3d50 Mon Sep 17 00:00:00 2001 From: Jane Lusby Date: Fri, 11 Mar 2022 11:59:05 -0800 Subject: [PATCH 07/17] more clarifications --- src/feature-lifecycle/stabilization.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/src/feature-lifecycle/stabilization.md b/src/feature-lifecycle/stabilization.md index 6dd7bba..857465a 100644 --- a/src/feature-lifecycle/stabilization.md +++ b/src/feature-lifecycle/stabilization.md @@ -1,7 +1,7 @@ # Stabilizing features -**Status:** Current -**Last Updated:** 2022/03/10 +* **Status:** Current +* **Last Updated:** 2022/03/10 Feature stabilization involves adding `#[stable]` attributes. They may be introduced alongside new trait impls or replace existing `#[unstable]` attributes. @@ -23,6 +23,8 @@ The **API Summary** section should include a precise description of what APIs ar The **Experience Report** section should include links to projects that use the feature being stabilized, or when applicable, projects that use crates that export the same API and describe the experience of using the feature in question. +You can see examples of stabilization reports in tracking issues [#88581](https://github.com/rust-lang/rust/issues/88581#issuecomment-1054642118) and [#29553](https://github.com/rust-lang/rust/issues/29553). + ## Before writing a PR to stabilize a feature Check to see if a FCP has completed first. If not, either ping `@rust-lang/libs` or leave a comment asking about the status of the feature. @@ -31,12 +33,12 @@ This will save you from opening a stabilization PR and having it need regular re ## Partial Stabilizations -When you only wish to stabilize a subset of an existing feature your first step should be to split the feature into multiple features, each with their own tracking issues. When you're splitting up the feature, you should always introduce a new feature name for the portion being stabilized and leave the existing feature for the portions left unstable, that way existing users of that feature are not left in a broken state. - -You can see an example of partially stabilizing a feature with tracking issue [#71146](https://github.com/rust-lang/rust/issues/71146) and partial stabilization + tracking PR [#94640](https://github.com/rust-lang/rust/pull/94640). +When you only wish to stabilize a subset of an existing feature you should skip creating a new tracking issue and instead create a partial stabilization + tracking PR for the subset of the feature being stabilized. When you're splitting up the feature, you should always introduce a new feature name for the portion being stabilized and leave the existing feature for the portions left unstable, that way existing users of that feature are not left in a broken state. If you're unsure if a feature is ready for partial stabilization the first step should be to ask in the relevant tracking issue and get assistance from other participants in that discussion. In some cases the tracking issue may not have many other active participants, so if you're ever having trouble getting any feedback please ping one of the [libs team reviewers](https://github.com/rust-lang/highfive/blob/master/highfive/configs/rust-lang/rust.json) directly to request assistance. +You can see an example of partially stabilizing a feature with tracking issue [#71146](https://github.com/rust-lang/rust/issues/71146) and partial stabilization + tracking PR [#94640](https://github.com/rust-lang/rust/pull/94640). + ## When there's `const` involved Const functions can be stabilized in a PR that replaces `#[rustc_const_unstable]` attributes with `#[rustc_const_stable]` ones. The [Constant Evaluation WG](https://github.com/rust-lang/const-eval) should be pinged for input on whether or not the `const`-ness is something we want to commit to. If it is an intrinsic being exposed that is const-stabilized then `@rust-lang/lang` should also be included in the FCP. @@ -100,6 +102,7 @@ The compiler builds with nightly features allowed, so you may find uses of the f To stabilize a feature, follow these steps: +0. Create a stabiliation report in the tracking issue for the feature being stabilized. 0. (Optional) For partial stabilizations, create a new partial stabilization + tracking PR for the subset of the issue being stabilized under a newly introduced feature name. 0. Ask a **@rust-lang/libs-api** member to start an FCP on the tracking issue and wait for the FCP to complete (with `disposition-merge`). 0. Change `#[unstable(...)]` to `#[stable(since = "version")]`. `version` should be the *current nightly*, i.e. stable+2. You can see which version is the current nightly [on Forge](https://forge.rust-lang.org/#current-release-versions). From 1e6c361dd25614f62421e868c430f446e1287c14 Mon Sep 17 00:00:00 2001 From: Jane Lusby Date: Mon, 14 Mar 2022 09:39:24 -0700 Subject: [PATCH 08/17] Apply suggestions from code review Co-authored-by: Mara Bos --- src/feature-lifecycle/stabilization.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/feature-lifecycle/stabilization.md b/src/feature-lifecycle/stabilization.md index 857465a..dd318e1 100644 --- a/src/feature-lifecycle/stabilization.md +++ b/src/feature-lifecycle/stabilization.md @@ -1,7 +1,7 @@ # Stabilizing features * **Status:** Current -* **Last Updated:** 2022/03/10 +* **Last Updated:** 2022-03-10 Feature stabilization involves adding `#[stable]` attributes. They may be introduced alongside new trait impls or replace existing `#[unstable]` attributes. @@ -9,7 +9,7 @@ Stabilization goes through the Libs FCP[^1] process, which occurs on the [tracki ## When is an FCP appropriate? -Once an unstable feature has been well-tested with no outstanding concerns, anyone may push for it's stabilization. +Once an unstable feature has been well-tested with no outstanding concerns, anyone may push for its stabilization. If you're unsure if a feature is ready for stabilization the first step should be to ask in the relevant tracking issue and get assistance from other participants in that discussion. In some cases the tracking issue may not have many other active participants, so if you're ever having trouble getting any feedback please ping one of the [libs team reviewers](https://github.com/rust-lang/highfive/blob/master/highfive/configs/rust-lang/rust.json) directly to request assistance. @@ -110,7 +110,7 @@ To stabilize a feature, follow these steps: 0. If applicable, change `#[rustc_const_unstable(...)]` to `#[rustc_const_stable(since = "version")]`. 0. Open a PR against `rust-lang/rust`. - Add the appropriate labels: `@rustbot modify labels: +T-libs-api`. - - Link to the tracking issue and say "Closes #XXXXX". + - Link to the tracking issue by adding "Closes #XXXXX". You can see an example of stabilizing a feature with [tracking issue #81656 with FCP](https://github.com/rust-lang/rust/issues/81656) and the associated [implementation PR #84642](https://github.com/rust-lang/rust/pull/84642). From 4fc10426ef3525deff88251d70b48138ce8c6e07 Mon Sep 17 00:00:00 2001 From: Jane Lusby Date: Mon, 14 Mar 2022 09:45:04 -0700 Subject: [PATCH 09/17] note that api summary can link back to top level tracking issue comment if up to date --- src/feature-lifecycle/stabilization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/feature-lifecycle/stabilization.md b/src/feature-lifecycle/stabilization.md index dd318e1..2b3f9f6 100644 --- a/src/feature-lifecycle/stabilization.md +++ b/src/feature-lifecycle/stabilization.md @@ -19,7 +19,7 @@ Once a feature is ready for stabilization the first step of the FCP process is w The **Implementation History** section should summarize the initial discussion during the implementation PR, every change that has been made to the feature since the initial implementation, all issues that were raised during the lifetime of the feature, and how they were resolved. -The **API Summary** section should include a precise description of what APIs are being introduced to the standard libraries. The libs team maintains a tool for this called [`cargo unstable-api`](https://github.com/rust-lang/libs-team/tree/main/tools/unstable-api) that can be used to generate these API summaries in some cases. *Note* the current implementation of this tool is fragile and does not work in all cases. We hope to have a more permanent version of this tool in the future that is built ontop of either rustdoc or rustc's own APIs. +The **API Summary** section should include a precise description of what APIs are being introduced to the standard libraries. This can often be a simple link back to the top level comment if it's up to date, but in situations it may not be possible to edit the original tracking issue to fix outdated information, such as when the author of the stabilization report is not the author of the tracking issue itself. The libs team maintains a tool for this called [`cargo unstable-api`](https://github.com/rust-lang/libs-team/tree/main/tools/unstable-api) that can be used to generate these API summaries in some cases. *Note* the current implementation of this tool is fragile and does not work in all cases. We hope to have a more permanent version of this tool in the future that is built ontop of either rustdoc or rustc's own APIs. The **Experience Report** section should include links to projects that use the feature being stabilized, or when applicable, projects that use crates that export the same API and describe the experience of using the feature in question. From 60625ff37f4e0c1fb741704fcfd7909440e49341 Mon Sep 17 00:00:00 2001 From: Jane Lusby Date: Mon, 14 Mar 2022 09:46:07 -0700 Subject: [PATCH 10/17] remove references to tracking PRs --- src/feature-lifecycle/stabilization.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/feature-lifecycle/stabilization.md b/src/feature-lifecycle/stabilization.md index 2b3f9f6..e7c3603 100644 --- a/src/feature-lifecycle/stabilization.md +++ b/src/feature-lifecycle/stabilization.md @@ -33,11 +33,11 @@ This will save you from opening a stabilization PR and having it need regular re ## Partial Stabilizations -When you only wish to stabilize a subset of an existing feature you should skip creating a new tracking issue and instead create a partial stabilization + tracking PR for the subset of the feature being stabilized. When you're splitting up the feature, you should always introduce a new feature name for the portion being stabilized and leave the existing feature for the portions left unstable, that way existing users of that feature are not left in a broken state. +When you only wish to stabilize a subset of an existing feature you should skip creating a new tracking issue and instead create a partial stabilization PR for the subset of the feature being stabilized. When you're splitting up the feature, you should always introduce a new feature name for the portion being stabilized and leave the existing feature for the portions left unstable, that way existing users of that feature are not left in a broken state. If you're unsure if a feature is ready for partial stabilization the first step should be to ask in the relevant tracking issue and get assistance from other participants in that discussion. In some cases the tracking issue may not have many other active participants, so if you're ever having trouble getting any feedback please ping one of the [libs team reviewers](https://github.com/rust-lang/highfive/blob/master/highfive/configs/rust-lang/rust.json) directly to request assistance. -You can see an example of partially stabilizing a feature with tracking issue [#71146](https://github.com/rust-lang/rust/issues/71146) and partial stabilization + tracking PR [#94640](https://github.com/rust-lang/rust/pull/94640). +You can see an example of partially stabilizing a feature with tracking issue [#71146](https://github.com/rust-lang/rust/issues/71146) and partial stabilization PR [#94640](https://github.com/rust-lang/rust/pull/94640). ## When there's `const` involved @@ -103,7 +103,7 @@ The compiler builds with nightly features allowed, so you may find uses of the f To stabilize a feature, follow these steps: 0. Create a stabiliation report in the tracking issue for the feature being stabilized. -0. (Optional) For partial stabilizations, create a new partial stabilization + tracking PR for the subset of the issue being stabilized under a newly introduced feature name. +0. (Optional) For partial stabilizations, create a new partial stabilization PR for the subset of the issue being stabilized under a newly introduced feature name. 0. Ask a **@rust-lang/libs-api** member to start an FCP on the tracking issue and wait for the FCP to complete (with `disposition-merge`). 0. Change `#[unstable(...)]` to `#[stable(since = "version")]`. `version` should be the *current nightly*, i.e. stable+2. You can see which version is the current nightly [on Forge](https://forge.rust-lang.org/#current-release-versions). 0. Remove `#![feature(...)]` from any test or doc-test for this API. If the feature is used in the compiler or tools, remove it from there as well. From 0e08aaf57fcd8165decfef00884587aaaec08baa Mon Sep 17 00:00:00 2001 From: Jane Lusby Date: Mon, 14 Mar 2022 09:53:06 -0700 Subject: [PATCH 11/17] reframe well-tested comment around API design --- src/feature-lifecycle/stabilization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/feature-lifecycle/stabilization.md b/src/feature-lifecycle/stabilization.md index e7c3603..f1d7e19 100644 --- a/src/feature-lifecycle/stabilization.md +++ b/src/feature-lifecycle/stabilization.md @@ -9,7 +9,7 @@ Stabilization goes through the Libs FCP[^1] process, which occurs on the [tracki ## When is an FCP appropriate? -Once an unstable feature has been well-tested with no outstanding concerns, anyone may push for its stabilization. +Once an unstable feature's API design space (e.g. alternative APIs) has been fully explored with no outstanding concerns, anyone may push for its stabilization. If you're unsure if a feature is ready for stabilization the first step should be to ask in the relevant tracking issue and get assistance from other participants in that discussion. In some cases the tracking issue may not have many other active participants, so if you're ever having trouble getting any feedback please ping one of the [libs team reviewers](https://github.com/rust-lang/highfive/blob/master/highfive/configs/rust-lang/rust.json) directly to request assistance. From 80723b99f64b6aa4c4c0b5f551bc07a83b0f1fdc Mon Sep 17 00:00:00 2001 From: Jane Lusby Date: Mon, 14 Mar 2022 11:55:17 -0700 Subject: [PATCH 12/17] direct people to the exact nightly version rather than forge --- src/feature-lifecycle/stabilization.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/feature-lifecycle/stabilization.md b/src/feature-lifecycle/stabilization.md index f1d7e19..1af678d 100644 --- a/src/feature-lifecycle/stabilization.md +++ b/src/feature-lifecycle/stabilization.md @@ -68,7 +68,7 @@ You'll need to change that to a `#[stable]` attribute with a version: #[stable(feature = "total_cmp", since = "1.61.0")] ``` -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/#current-release-versions). Specifically, you'll want to 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. +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 [`src/version`](https://github.com/rust-lang/rust/blob/master/src/version) on the current master branch of `rust-lang/rust`. Specifically, you'll want to 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. ### Remove feature gates from doctests @@ -105,7 +105,7 @@ To stabilize a feature, follow these steps: 0. Create a stabiliation report in the tracking issue for the feature being stabilized. 0. (Optional) For partial stabilizations, create a new partial stabilization PR for the subset of the issue being stabilized under a newly introduced feature name. 0. Ask a **@rust-lang/libs-api** member to start an FCP on the tracking issue and wait for the FCP to complete (with `disposition-merge`). -0. Change `#[unstable(...)]` to `#[stable(since = "version")]`. `version` should be the *current nightly*, i.e. stable+2. You can see which version is the current nightly [on Forge](https://forge.rust-lang.org/#current-release-versions). +0. Change `#[unstable(...)]` to `#[stable(since = "version")]`. `version` should be the *current nightly*, i.e. stable+2. You can see which version is the current nightly in [`src/version`](https://github.com/rust-lang/rust/blob/master/src/version) on the master branch of `rust-lang/rust`. 0. Remove `#![feature(...)]` from any test or doc-test for this API. If the feature is used in the compiler or tools, remove it from there as well. 0. If applicable, change `#[rustc_const_unstable(...)]` to `#[rustc_const_stable(since = "version")]`. 0. Open a PR against `rust-lang/rust`. From 26a65de7306a07b5402bcdabe260307be4b2214a Mon Sep 17 00:00:00 2001 From: Jane Lusby Date: Wed, 16 Mar 2022 11:42:59 -0700 Subject: [PATCH 13/17] remove recommendation on partial stabilization feature names --- src/feature-lifecycle/stabilization.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/feature-lifecycle/stabilization.md b/src/feature-lifecycle/stabilization.md index 1af678d..15f09a6 100644 --- a/src/feature-lifecycle/stabilization.md +++ b/src/feature-lifecycle/stabilization.md @@ -33,7 +33,7 @@ This will save you from opening a stabilization PR and having it need regular re ## Partial Stabilizations -When you only wish to stabilize a subset of an existing feature you should skip creating a new tracking issue and instead create a partial stabilization PR for the subset of the feature being stabilized. When you're splitting up the feature, you should always introduce a new feature name for the portion being stabilized and leave the existing feature for the portions left unstable, that way existing users of that feature are not left in a broken state. +When you only wish to stabilize a subset of an existing feature you should skip creating a new tracking issue and instead create a partial stabilization PR for the subset of the feature being stabilized. If you're unsure if a feature is ready for partial stabilization the first step should be to ask in the relevant tracking issue and get assistance from other participants in that discussion. In some cases the tracking issue may not have many other active participants, so if you're ever having trouble getting any feedback please ping one of the [libs team reviewers](https://github.com/rust-lang/highfive/blob/master/highfive/configs/rust-lang/rust.json) directly to request assistance. @@ -103,7 +103,7 @@ The compiler builds with nightly features allowed, so you may find uses of the f To stabilize a feature, follow these steps: 0. Create a stabiliation report in the tracking issue for the feature being stabilized. -0. (Optional) For partial stabilizations, create a new partial stabilization PR for the subset of the issue being stabilized under a newly introduced feature name. +0. (Optional) For partial stabilizations, create a new partial stabilization PR for the subset of the issue being stabilized. 0. Ask a **@rust-lang/libs-api** member to start an FCP on the tracking issue and wait for the FCP to complete (with `disposition-merge`). 0. Change `#[unstable(...)]` to `#[stable(since = "version")]`. `version` should be the *current nightly*, i.e. stable+2. You can see which version is the current nightly in [`src/version`](https://github.com/rust-lang/rust/blob/master/src/version) on the master branch of `rust-lang/rust`. 0. Remove `#![feature(...)]` from any test or doc-test for this API. If the feature is used in the compiler or tools, remove it from there as well. From accbcbc2cda50ed8f836fbbae908016f31fb7d6c Mon Sep 17 00:00:00 2001 From: Jane Lusby Date: Wed, 16 Mar 2022 14:18:42 -0700 Subject: [PATCH 14/17] integrate additional feedback from libs-api team meeting --- src/feature-lifecycle/stabilization.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/feature-lifecycle/stabilization.md b/src/feature-lifecycle/stabilization.md index 15f09a6..aed22af 100644 --- a/src/feature-lifecycle/stabilization.md +++ b/src/feature-lifecycle/stabilization.md @@ -15,13 +15,13 @@ If you're unsure if a feature is ready for stabilization the first step should b ## Stabilization Report -Once a feature is ready for stabilization the first step of the FCP process is writing a stabilization report. Stabilization reports consist of three primary sections, a implementation history, an API summary, and an experience report. +Once a feature is ready for stabilization the first step of the FCP process is writing a stabilization report. Stabilization reports are not mandatory but they are heavily encouraged, and may be mandated by library API team members if they feel it necessary. The purpose of stabilization reports is to help reviewers more quickly make decisions and to simplify the process of documenting stabilized APIs in release notes. Stabilization reports consist of three primary sections, a implementation history, an API summary, and an experience report. The **Implementation History** section should summarize the initial discussion during the implementation PR, every change that has been made to the feature since the initial implementation, all issues that were raised during the lifetime of the feature, and how they were resolved. The **API Summary** section should include a precise description of what APIs are being introduced to the standard libraries. This can often be a simple link back to the top level comment if it's up to date, but in situations it may not be possible to edit the original tracking issue to fix outdated information, such as when the author of the stabilization report is not the author of the tracking issue itself. The libs team maintains a tool for this called [`cargo unstable-api`](https://github.com/rust-lang/libs-team/tree/main/tools/unstable-api) that can be used to generate these API summaries in some cases. *Note* the current implementation of this tool is fragile and does not work in all cases. We hope to have a more permanent version of this tool in the future that is built ontop of either rustdoc or rustc's own APIs. -The **Experience Report** section should include links to projects that use the feature being stabilized, or when applicable, projects that use crates that export the same API and describe the experience of using the feature in question. +The **Experience Report** section should include concrete usecases of users who have wanted to use the feature and who have tested that it works for their needs. The experience report should include a brief summary of the experience of using that feature. Ideally this would include links to commits or branches where the feature was integrated with their project, but this is not a requirement. Alternatively, users can provide usage examples of crates that export an identical API to the one being stabilized. You can see examples of stabilization reports in tracking issues [#88581](https://github.com/rust-lang/rust/issues/88581#issuecomment-1054642118) and [#29553](https://github.com/rust-lang/rust/issues/29553). From 405a608fec07a1a7368e747116237dae85bd5f00 Mon Sep 17 00:00:00 2001 From: Jane Lusby Date: Mon, 21 Mar 2022 16:01:37 -0700 Subject: [PATCH 15/17] fix line that said to ping libs instead of libs-api --- src/feature-lifecycle/stabilization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/feature-lifecycle/stabilization.md b/src/feature-lifecycle/stabilization.md index aed22af..ee764c8 100644 --- a/src/feature-lifecycle/stabilization.md +++ b/src/feature-lifecycle/stabilization.md @@ -27,7 +27,7 @@ You can see examples of stabilization reports in tracking issues [#88581](https: ## Before writing a PR to stabilize a feature -Check to see if a FCP has completed first. If not, either ping `@rust-lang/libs` or leave a comment asking about the status of the feature. +Check to see if a FCP has completed first. If not, either ping `@rust-lang/libs-api` or leave a comment asking about the status of the feature. This will save you from opening a stabilization PR and having it need regular rebasing while the FCP process runs its course. From 56f2d1bc1da767868e6dc3e1ea761dc23c78ec27 Mon Sep 17 00:00:00 2001 From: Jane Lusby Date: Fri, 27 May 2022 12:34:44 -0700 Subject: [PATCH 16/17] Update src/feature-lifecycle/stabilization.md Co-authored-by: Josh Triplett --- src/feature-lifecycle/stabilization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/feature-lifecycle/stabilization.md b/src/feature-lifecycle/stabilization.md index ee764c8..b4dd479 100644 --- a/src/feature-lifecycle/stabilization.md +++ b/src/feature-lifecycle/stabilization.md @@ -5,7 +5,7 @@ Feature stabilization involves adding `#[stable]` attributes. They may be introduced alongside new trait impls or replace existing `#[unstable]` attributes. -Stabilization goes through the Libs FCP[^1] process, which occurs on the [tracking issue](./tracking-issues.md) for the feature. +Stabilization goes through the Libs FCP[^1] process, which typically occurs on the [tracking issue](./tracking-issues.md) for the feature. ## When is an FCP appropriate? From 31712eae69d2ce6255203ed94a76e335e50f6050 Mon Sep 17 00:00:00 2001 From: Jane Lusby Date: Fri, 27 May 2022 12:59:31 -0700 Subject: [PATCH 17/17] final cleanup for publication --- src/feature-lifecycle/stabilization.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/src/feature-lifecycle/stabilization.md b/src/feature-lifecycle/stabilization.md index b4dd479..e5d60a4 100644 --- a/src/feature-lifecycle/stabilization.md +++ b/src/feature-lifecycle/stabilization.md @@ -1,11 +1,11 @@ # Stabilizing features * **Status:** Current -* **Last Updated:** 2022-03-10 +* **Last Updated:** 2022-05-27 Feature stabilization involves adding `#[stable]` attributes. They may be introduced alongside new trait impls or replace existing `#[unstable]` attributes. -Stabilization goes through the Libs FCP[^1] process, which typically occurs on the [tracking issue](./tracking-issues.md) for the feature. +Stabilization goes through the Libs FCP (Final Comment Period) process, which typically occurs on the [tracking issue](./tracking-issues.md) for the feature. ## When is an FCP appropriate? @@ -19,11 +19,13 @@ Once a feature is ready for stabilization the first step of the FCP process is w The **Implementation History** section should summarize the initial discussion during the implementation PR, every change that has been made to the feature since the initial implementation, all issues that were raised during the lifetime of the feature, and how they were resolved. -The **API Summary** section should include a precise description of what APIs are being introduced to the standard libraries. This can often be a simple link back to the top level comment if it's up to date, but in situations it may not be possible to edit the original tracking issue to fix outdated information, such as when the author of the stabilization report is not the author of the tracking issue itself. The libs team maintains a tool for this called [`cargo unstable-api`](https://github.com/rust-lang/libs-team/tree/main/tools/unstable-api) that can be used to generate these API summaries in some cases. *Note* the current implementation of this tool is fragile and does not work in all cases. We hope to have a more permanent version of this tool in the future that is built ontop of either rustdoc or rustc's own APIs. +The **API Summary** section should include a precise description of what APIs are being introduced to the standard libraries. This can often be a simple link back to the top level comment if it's up to date, but in some situations it may not be possible to edit the original tracking issue to fix outdated information, such as when the author of the stabilization report is not the author of the tracking issue itself. + +The libs team maintains a tool for this called [`cargo unstable-api`](https://github.com/rust-lang/libs-team/tree/main/tools/unstable-api) that can be used to generate these API summaries in some cases. *Note* the current implementation of this tool is fragile and does not work in all cases. We hope to have a more permanent version of this tool in the future that is built ontop of either rustdoc or rustc's own APIs. The **Experience Report** section should include concrete usecases of users who have wanted to use the feature and who have tested that it works for their needs. The experience report should include a brief summary of the experience of using that feature. Ideally this would include links to commits or branches where the feature was integrated with their project, but this is not a requirement. Alternatively, users can provide usage examples of crates that export an identical API to the one being stabilized. -You can see examples of stabilization reports in tracking issues [#88581](https://github.com/rust-lang/rust/issues/88581#issuecomment-1054642118) and [#29553](https://github.com/rust-lang/rust/issues/29553). +You can see an example of a stabilization report in [#88581](https://github.com/rust-lang/rust/issues/88581#issuecomment-1054642118). ## Before writing a PR to stabilize a feature @@ -68,7 +70,7 @@ You'll need to change that to a `#[stable]` attribute with a version: #[stable(feature = "total_cmp", since = "1.61.0")] ``` -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 [`src/version`](https://github.com/rust-lang/rust/blob/master/src/version) on the current master branch of `rust-lang/rust`. Specifically, you'll want to 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. +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 [`src/version`](https://github.com/rust-lang/rust/blob/master/src/version) on the current master branch of `rust-lang/rust`. ### Remove feature gates from doctests @@ -114,5 +116,3 @@ To stabilize a feature, follow these steps: You can see an example of stabilizing a feature with [tracking issue #81656 with FCP](https://github.com/rust-lang/rust/issues/81656) and the associated [implementation PR #84642](https://github.com/rust-lang/rust/pull/84642). -[^1]: FCP stands for final comment period -