|
1 | 1 | # Stabilizing features
|
2 | 2 |
|
3 | 3 | **Status:** Current
|
4 |
| -**Last Updated:** 2022/03/03 |
| 4 | +**Last Updated:** 2022/03/10 |
5 | 5 |
|
6 | 6 | Feature stabilization involves adding `#[stable]` attributes. They may be introduced alongside new trait impls or replace existing `#[unstable]` attributes.
|
7 | 7 |
|
8 |
| -Stabilization goes through the Libs FCP process, which occurs on the [tracking issue](./tracking-issues.md) for the feature. |
| 8 | +Stabilization goes through the Libs FCP[^1] process, which occurs on the [tracking issue](./tracking-issues.md) for the feature. |
| 9 | + |
| 10 | +## When is an FCP appropriate? |
| 11 | + |
| 12 | +Once an unstable feature has been well-tested with no outstanding concerns, |
| 13 | +anyone may push for it's stabilization. If you're unsure if a feature is ready |
| 14 | +for stabilization the first step should be to ask in the relevant tracking |
| 15 | +issue and get assistance from other participants in that discussion. In some |
| 16 | +cases the tracking issue may not have many other active participants, so if |
| 17 | +you're ever having trouble getting any feedback please ping one of the [libs |
| 18 | +team |
| 19 | +reviewers](https://github.com/rust-lang/highfive/blob/master/highfive/configs/rust-lang/rust.json) |
| 20 | +directly to request assistance. |
| 21 | + |
| 22 | +## Stabilization Report |
| 23 | + |
| 24 | +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. |
| 25 | + |
| 26 | +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. |
| 27 | + |
| 28 | +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. |
| 29 | + |
| 30 | +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. |
9 | 31 |
|
10 | 32 | ## Before writing a PR to stabilize a feature
|
11 | 33 |
|
@@ -93,3 +115,4 @@ To stabilize a feature, follow these steps:
|
93 | 115 |
|
94 | 116 | 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).
|
95 | 117 |
|
| 118 | +[^1]: FCP stands for final comment period |
0 commit comments