From 55b5e8e4e6fa31587d02bed20472a2be2b2671df Mon Sep 17 00:00:00 2001 From: Rajkumar Natarajan Date: Tue, 15 Jan 2019 17:07:06 -0500 Subject: [PATCH 01/15] issue_130_stabilization_guide --- src/SUMMARY.md | 1 + src/stabilization_guide.md | 181 +++++++++++++++++++++++++++++++++++++ 2 files changed, 182 insertions(+) create mode 100644 src/stabilization_guide.md diff --git a/src/SUMMARY.md b/src/SUMMARY.md index bfb112ce6..9bdf89278 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -6,6 +6,7 @@ - [Build and Install distribution artifacts](./build-install-distribution-artifacts.md) - [Documenting Compiler](./compiler-documenting.md) - [Coding conventions](./conventions.md) +- [Stabilizing Features](./stabilization_guide.md) - [Walkthrough: a typical contribution](./walkthrough.md) - [The compiler testing framework](./tests/intro.md) - [Running tests](./tests/running.md) diff --git a/src/stabilization_guide.md b/src/stabilization_guide.md new file mode 100644 index 000000000..af86b450e --- /dev/null +++ b/src/stabilization_guide.md @@ -0,0 +1,181 @@ + +# Request for stabilization + + Once an unstable feature has been well-tested with no outstanding + concern, anyone may push for its stabilization. It involves the + following steps. + + - Documentation PRs + - Write a stabilization report + - FCP + - Stabilization PR + +## Documentation PRs + + Prepare PRs to update documentations involing this new feature. + You need to submit PRs for repositories The Reference, The Book + and Rust by Example. + Maintainers of these repositories will keep these PRs open until + the whole stabilization process has completed. Meanwhile, we can + proceed to the next step. + +## Write a stabilization report + + Find the tracking issue of the feature, and create a short + stabilization report. Essentially this would be a brief summary + of the feature plus some links to test cases showing it works + as expected, along with a list of edge cases that came up and + and were considered. This is a minimal "due diligence" that + we do before stabilizing. + + The report should contain: + + - A summary, showing examples (e.g. code snippets) what is + enabled by this feature. + - Links to test cases in our test suite regarding this feature + and describe the feature's behavior on encountering edge cases. + - Links to the documentations (the PRs we have made in the + previous steps). + - Any other relevant information(Examples of such reports can + be found in rust-lang/rust#44494 and rust-lang/rust#28237). + +## FCP + +If any member of the team responsible for tracking this +feature agrees with stabilizing this feature, they will +start the FCP (final-comment-period) process by +commenting + + ```bash + @rfcbot fcp merge + ``` + +The rest of the team members will review the proposal. If the final +decision is to stabilize, we proceed to do the actual code modification. + +## Stabilization PR + +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 you on a little tour +through the source code. + +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. + +Note: Before we stabilize any feature, it is rule that it should appear +in the documentation. + +### Updating the feature-gate listing + +There is a central listing of feature-gates in +`src/libsyntax/feature_gate.rs`. Search for the `declare_features!` +macro. There should be an entry for the feature you are aiming to +stabilize, something like (this example is taken from +[rust-lang/rust#32409]: + + ``` + // pub(restricted) visibilities (RFC 1422) + (active, pub_restricted, "1.9.0", Some(32409)), + ``` +The above line should be moved down to the area for "accepted" +features, declared below in a separate call to `declare_features!`. +When it is done, it should look like: + + ``` + // pub(restricted) visibilities (RFC 1422) + (accepted, pub_restricted, "1.31.0", Some(32409)), + // ^^^^^^ 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 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 (what is currently beta, iow) was +1.30.0, hence I wrote 1.31.0 above. + +### Removing existing uses of the feature-gate + +Next search for the feature string (in this case, pub_restricted) +in the codebase to find where it appears. Change uses of +`#![feature(XXX)]` from the stdlib and rustc crates to be +`#![cfg_attr(stage0, feature(XXX))]`. This includes the feature-gate +only for stage0, which is built using the current beta (this is +needed because the feature is still unstable in the current beta). + +Also, remove those strings from any tests. If there are tests +specifically targeting the feature-gate (i.e., testing that the +feature-gate is required to use the feature, but nothing else), +simply remove the test. + +### Do not require the feature-gate to use the feature + +Most importantly, remove the code which flags an error if the +feature-gate is not present (since the feature is now considered +stable). If the feature can be detected because it employs some +new syntax, then a common place for that code to be is in the +same `feature_gate.rs`. For example, you might see code like this: + + ``` + gate_feature_post!(&self, pub_restricted, span, + "`pub(restricted)` syntax is experimental"); + ``` + +This `gate_feature_post!` macro prints an error if the +`pub_restricted` feature is not enabled. It is not needed +now that `#[pub_restricted]` is stable. + +For more subtle features, you may find code like this: + + ``` + if self.tcx.sess.features.borrow().pub_restricted { /* XXX */ } + ``` + +This `pub_restricted` field (obviously named after the feature) +would ordinarily be false if the feature flag is not present +and true if it is. So transform the code to assume that the field +is true. In this case, that would mean removing the `if` and +leaving just the `/* XXX */`. + + ``` + if self.tcx.sess.features.borrow().pub_restricted { /* XXX */ } + = becomes ==> + /* XXX */ + + if self.tcx.sess.features.borrow().pub_restricted && something { /* XXX */ } + = becomes ==> + if something { /* XXX */ } + ``` + +## Updating documentation + +If any documentation for this feature exists, it should be +in the `Unstable Book`, located at `src/doc/unstable-book`. +Regardless of its existence, the page for the feature gate +should be removed. + +If there was documentation there, integrating it into the +existing documentation is needed. + +If there wasn't documentation there, it needs to be added. + +Places that may need updated documentation: + + [The Reference]: this must be updated, in full detail. + [The Book]: this may or may not need updating, depending. + If you're not sure, please open an issue on this repository + and it can be discussed. + standard library documentation: as needed. Language features + often don't need this, but if it's a feature that changes + how good examples are written, such as when `?` was added + to the language, updating examples is important. + [Rust by Example]: as needed. + +[rust-lang/rust#32409]:https://github.com/rust-lang/rust/issues/32409 +[The Reference]: https://github.com/rust-lang-nursery/reference +[The Book]: https://github.com/rust-lang/book +[Rust by Example]: https://github.com/rust-lang/rust-by-example \ No newline at end of file From f1ebec464e4011723ff35944ae222847aab74da8 Mon Sep 17 00:00:00 2001 From: Who? Me?! Date: Tue, 15 Jan 2019 21:00:36 -0500 Subject: [PATCH 02/15] Update src/stabilization_guide.md Co-Authored-By: rajcspsg --- src/stabilization_guide.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/stabilization_guide.md b/src/stabilization_guide.md index af86b450e..db8b5c3f4 100644 --- a/src/stabilization_guide.md +++ b/src/stabilization_guide.md @@ -64,7 +64,7 @@ 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. -Note: Before we stabilize any feature, it is rule that it should appear +Note: Before we stabilize any feature, it's the rule that it should appear in the documentation. ### Updating the feature-gate listing @@ -178,4 +178,4 @@ Places that may need updated documentation: [rust-lang/rust#32409]:https://github.com/rust-lang/rust/issues/32409 [The Reference]: https://github.com/rust-lang-nursery/reference [The Book]: https://github.com/rust-lang/book -[Rust by Example]: https://github.com/rust-lang/rust-by-example \ No newline at end of file +[Rust by Example]: https://github.com/rust-lang/rust-by-example From e77ac30c1b81ea422098764e269c0c333b17aef9 Mon Sep 17 00:00:00 2001 From: Who? Me?! Date: Tue, 15 Jan 2019 21:02:20 -0500 Subject: [PATCH 03/15] Update src/stabilization_guide.md Co-Authored-By: rajcspsg --- src/stabilization_guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/stabilization_guide.md b/src/stabilization_guide.md index db8b5c3f4..22ec49f8a 100644 --- a/src/stabilization_guide.md +++ b/src/stabilization_guide.md @@ -91,7 +91,7 @@ When it is done, it should look like: 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 https://forge.rust-lang.org/, which will guide +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 From d27e29ea36abcca418b9a426f2e83c241f057aa8 Mon Sep 17 00:00:00 2001 From: Who? Me?! Date: Tue, 15 Jan 2019 21:02:36 -0500 Subject: [PATCH 04/15] Update src/stabilization_guide.md Co-Authored-By: rajcspsg --- src/stabilization_guide.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/stabilization_guide.md b/src/stabilization_guide.md index 22ec49f8a..3af4aff73 100644 --- a/src/stabilization_guide.md +++ b/src/stabilization_guide.md @@ -147,7 +147,9 @@ leaving just the `/* XXX */`. /* XXX */ if self.tcx.sess.features.borrow().pub_restricted && something { /* XXX */ } - = becomes ==> + ``` +becomes +```rust if something { /* XXX */ } ``` From 70757cf41fe20dfadd0b102931c31ea5ab730e25 Mon Sep 17 00:00:00 2001 From: Who? Me?! Date: Tue, 15 Jan 2019 21:02:51 -0500 Subject: [PATCH 05/15] Update src/stabilization_guide.md Co-Authored-By: rajcspsg --- src/stabilization_guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/stabilization_guide.md b/src/stabilization_guide.md index 3af4aff73..d21fbb174 100644 --- a/src/stabilization_guide.md +++ b/src/stabilization_guide.md @@ -157,7 +157,7 @@ becomes If any documentation for this feature exists, it should be in the `Unstable Book`, located at `src/doc/unstable-book`. -Regardless of its existence, the page for the feature gate +If it exists, the page for the feature gate should be removed. If there was documentation there, integrating it into the From 1b116200f50139d60be1e2d87433067fe02b8e6b Mon Sep 17 00:00:00 2001 From: Who? Me?! Date: Tue, 15 Jan 2019 21:03:13 -0500 Subject: [PATCH 06/15] Update src/stabilization_guide.md Co-Authored-By: rajcspsg --- src/stabilization_guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/stabilization_guide.md b/src/stabilization_guide.md index d21fbb174..a245d170b 100644 --- a/src/stabilization_guide.md +++ b/src/stabilization_guide.md @@ -100,7 +100,7 @@ writing, the next stable release (what is currently beta, iow) was ### Removing existing uses of the feature-gate -Next search for the feature string (in this case, pub_restricted) +Next search for the feature string (in this case, `pub_restricted`) in the codebase to find where it appears. Change uses of `#![feature(XXX)]` from the stdlib and rustc crates to be `#![cfg_attr(stage0, feature(XXX))]`. This includes the feature-gate From 3590fb3e1f2bbf9f9d62877efd0549ad62749afd Mon Sep 17 00:00:00 2001 From: Who? Me?! Date: Tue, 15 Jan 2019 21:10:56 -0500 Subject: [PATCH 07/15] Update src/stabilization_guide.md Co-Authored-By: rajcspsg --- src/stabilization_guide.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/stabilization_guide.md b/src/stabilization_guide.md index a245d170b..d73e96d8c 100644 --- a/src/stabilization_guide.md +++ b/src/stabilization_guide.md @@ -143,7 +143,9 @@ leaving just the `/* XXX */`. ``` if self.tcx.sess.features.borrow().pub_restricted { /* XXX */ } - = becomes ==> + ``` +becomes +```rust /* XXX */ if self.tcx.sess.features.borrow().pub_restricted && something { /* XXX */ } From a27b5a5be062e91a6fd8408ebdd4729f10f71631 Mon Sep 17 00:00:00 2001 From: Rajkumar Natarajan Date: Tue, 15 Jan 2019 22:22:36 -0500 Subject: [PATCH 08/15] issue_180 incorporated the review comments --- src/stabilization_guide.md | 157 +++++++++++++++++-------------------- 1 file changed, 74 insertions(+), 83 deletions(-) diff --git a/src/stabilization_guide.md b/src/stabilization_guide.md index d73e96d8c..2974f6314 100644 --- a/src/stabilization_guide.md +++ b/src/stabilization_guide.md @@ -1,43 +1,61 @@ - # Request for stabilization - Once an unstable feature has been well-tested with no outstanding - concern, anyone may push for its stabilization. It involves the - following steps. +Once an unstable feature has been well-tested with no outstanding +concern, anyone may push for its stabilization. It involves the +following steps. - - Documentation PRs - - Write a stabilization report - - FCP - - Stabilization PR +- Documentation PRs +- Write a stabilization report +- FCP +- Stabilization PR ## Documentation PRs - Prepare PRs to update documentations involing this new feature. - You need to submit PRs for repositories The Reference, The Book - and Rust by Example. - Maintainers of these repositories will keep these PRs open until - the whole stabilization process has completed. Meanwhile, we can - proceed to the next step. +If any documentation for this feature exists, it should be +in the `Unstable Book`, located at `src/doc/unstable-book`. +If it exists, the page for the feature gate should be removed. + +If there was documentation there, integrating it into the +existing documentation is needed. + +If there wasn't documentation there, it needs to be added. + +Places that may need updated documentation: + + [The Reference]: This must be updated, in full detail. + [The Book]: This may or may not need updating, depends. + If you're not sure, please open an issue on this repository + and it can be discussed. + standard library documentation: As needed. Language features + often don't need this, but if it's a feature that changes + how good examples are written, such as when `?` was added + to the language, updating examples is important. + [Rust by Example]: As needed. + +Prepare PRs to update documentations invovling this new feature +for repositories mentioned above.Maintainers of these repositories +will keep these PRs open until the whole stabilization process +has completed. Meanwhile, we can proceed to the next step. ## Write a stabilization report - Find the tracking issue of the feature, and create a short - stabilization report. Essentially this would be a brief summary - of the feature plus some links to test cases showing it works - as expected, along with a list of edge cases that came up and - and were considered. This is a minimal "due diligence" that - we do before stabilizing. +Find the tracking issue of the feature, and create a short +stabilization report. Essentially this would be a brief summary +of the feature plus some links to test cases showing it works +as expected, along with a list of edge cases that came up and +and were considered. This is a minimal "due diligence" that +we do before stabilizing. - The report should contain: +The report should contain: - - A summary, showing examples (e.g. code snippets) what is - enabled by this feature. - - Links to test cases in our test suite regarding this feature - and describe the feature's behavior on encountering edge cases. - - Links to the documentations (the PRs we have made in the - previous steps). - - Any other relevant information(Examples of such reports can - be found in rust-lang/rust#44494 and rust-lang/rust#28237). +- A summary, showing examples (e.g. code snippets) what is + enabled by this feature. +- Links to test cases in our test suite regarding this feature + and describe the feature's behavior on encountering edge cases. +- Links to the documentations (the PRs we have made in the + previous steps). +- Any other relevant information(Examples of such reports can + be found in rust-lang/rust#44494 and rust-lang/rust#28237). ## FCP @@ -46,9 +64,9 @@ feature agrees with stabilizing this feature, they will start the FCP (final-comment-period) process by commenting - ```bash - @rfcbot fcp merge - ``` +```bash +@rfcbot fcp merge +``` The rest of the team members will review the proposal. If the final decision is to stabilize, we proceed to do the actual code modification. @@ -75,19 +93,20 @@ macro. There should be an entry for the feature you are aiming to stabilize, something like (this example is taken from [rust-lang/rust#32409]: - ``` - // pub(restricted) visibilities (RFC 1422) - (active, pub_restricted, "1.9.0", Some(32409)), - ``` +```rust,ignore +// pub(restricted) visibilities (RFC 1422) +(active, pub_restricted, "1.9.0", Some(32409)), +``` + The above line should be moved down to the area for "accepted" features, declared below in a separate call to `declare_features!`. When it is done, it should look like: - ``` - // pub(restricted) visibilities (RFC 1422) - (accepted, pub_restricted, "1.31.0", Some(32409)), - // ^^^^^^ note that we changed this - ``` +```rust,ignore +// pub(restricted) visibilities (RFC 1422) +(accepted, pub_restricted, "1.31.0", Some(32409)), +// 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 @@ -120,10 +139,10 @@ stable). If the feature can be detected because it employs some new syntax, then a common place for that code to be is in the same `feature_gate.rs`. For example, you might see code like this: - ``` - gate_feature_post!(&self, pub_restricted, span, - "`pub(restricted)` syntax is experimental"); - ``` +```rust,ignore +gate_feature_post!(&self, pub_restricted, span, + "`pub(restricted)` syntax is experimental"); +``` This `gate_feature_post!` macro prints an error if the `pub_restricted` feature is not enabled. It is not needed @@ -131,9 +150,9 @@ now that `#[pub_restricted]` is stable. For more subtle features, you may find code like this: - ``` - if self.tcx.sess.features.borrow().pub_restricted { /* XXX */ } - ``` +```rust,ignore +if self.tcx.sess.features.borrow().pub_restricted { /* XXX */ } +``` This `pub_restricted` field (obviously named after the feature) would ordinarily be false if the feature flag is not present @@ -141,43 +160,15 @@ and true if it is. So transform the code to assume that the field is true. In this case, that would mean removing the `if` and leaving just the `/* XXX */`. - ``` - if self.tcx.sess.features.borrow().pub_restricted { /* XXX */ } - ``` +```rust,ignore +if self.tcx.sess.features.borrow().pub_restricted { /* XXX */ } becomes -```rust - /* XXX */ +/* XXX */ - if self.tcx.sess.features.borrow().pub_restricted && something { /* XXX */ } - ``` -becomes -```rust - if something { /* XXX */ } - ``` - -## Updating documentation - -If any documentation for this feature exists, it should be -in the `Unstable Book`, located at `src/doc/unstable-book`. -If it exists, the page for the feature gate -should be removed. - -If there was documentation there, integrating it into the -existing documentation is needed. - -If there wasn't documentation there, it needs to be added. - -Places that may need updated documentation: - - [The Reference]: this must be updated, in full detail. - [The Book]: this may or may not need updating, depending. - If you're not sure, please open an issue on this repository - and it can be discussed. - standard library documentation: as needed. Language features - often don't need this, but if it's a feature that changes - how good examples are written, such as when `?` was added - to the language, updating examples is important. - [Rust by Example]: as needed. +if self.tcx.sess.features.borrow().pub_restricted && something { /* XXX */ } + becomes +if something { /* XXX */ } +``` [rust-lang/rust#32409]:https://github.com/rust-lang/rust/issues/32409 [The Reference]: https://github.com/rust-lang-nursery/reference From 45b7b75dcc755cdbfd658762eb19e47a2c4cf873 Mon Sep 17 00:00:00 2001 From: Who? Me?! Date: Thu, 17 Jan 2019 14:04:50 -0500 Subject: [PATCH 09/15] Update src/stabilization_guide.md Co-Authored-By: rajcspsg --- src/stabilization_guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/stabilization_guide.md b/src/stabilization_guide.md index 2974f6314..a17eff162 100644 --- a/src/stabilization_guide.md +++ b/src/stabilization_guide.md @@ -114,7 +114,7 @@ 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 (what is currently beta, iow) was +writing, the next stable release (i.e. what is currently beta) was 1.30.0, hence I wrote 1.31.0 above. ### Removing existing uses of the feature-gate From 9e8fd175604beaaf3ca139bdf5121f1cfed35b77 Mon Sep 17 00:00:00 2001 From: Who? Me?! Date: Thu, 17 Jan 2019 14:05:13 -0500 Subject: [PATCH 10/15] Update src/stabilization_guide.md Co-Authored-By: rajcspsg --- src/stabilization_guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/stabilization_guide.md b/src/stabilization_guide.md index a17eff162..89407308d 100644 --- a/src/stabilization_guide.md +++ b/src/stabilization_guide.md @@ -121,7 +121,7 @@ writing, the next stable release (i.e. what is currently beta) was Next search for the feature string (in this case, `pub_restricted`) in the codebase to find where it appears. Change uses of -`#![feature(XXX)]` from the stdlib and rustc crates to be +`#![feature(XXX)]` from the `libstd` and any rustc crates to be `#![cfg_attr(stage0, feature(XXX))]`. This includes the feature-gate only for stage0, which is built using the current beta (this is needed because the feature is still unstable in the current beta). From 540b9ebf09bbd01162c37e2db721668767c9de8f Mon Sep 17 00:00:00 2001 From: Rajkumar Natarajan Date: Thu, 17 Jan 2019 14:09:41 -0500 Subject: [PATCH 11/15] issue 130 stabilization guide --- src/stabilization_guide.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/stabilization_guide.md b/src/stabilization_guide.md index 89407308d..e56313bb0 100644 --- a/src/stabilization_guide.md +++ b/src/stabilization_guide.md @@ -22,15 +22,15 @@ If there wasn't documentation there, it needs to be added. Places that may need updated documentation: - [The Reference]: This must be updated, in full detail. - [The Book]: This may or may not need updating, depends. +- [The Reference]: This must be updated, in full detail. +- [The Book]: This may or may not need updating, depends. If you're not sure, please open an issue on this repository and it can be discussed. - standard library documentation: As needed. Language features +- standard library documentation: As needed. Language features often don't need this, but if it's a feature that changes how good examples are written, such as when `?` was added to the language, updating examples is important. - [Rust by Example]: As needed. +- [Rust by Example]: As needed. Prepare PRs to update documentations invovling this new feature for repositories mentioned above.Maintainers of these repositories From 840e617d7c23e50310d038c67cad75908ad87bd3 Mon Sep 17 00:00:00 2001 From: Rajkumar Natarajan Date: Thu, 17 Jan 2019 14:20:24 -0500 Subject: [PATCH 12/15] issue 130 stabilization guide --- src/stabilization_guide.md | 5 ++++- src/walkthrough.md | 4 ---- 2 files changed, 4 insertions(+), 5 deletions(-) diff --git a/src/stabilization_guide.md b/src/stabilization_guide.md index e56313bb0..7f3c7321a 100644 --- a/src/stabilization_guide.md +++ b/src/stabilization_guide.md @@ -56,6 +56,8 @@ The report should contain: previous steps). - Any other relevant information(Examples of such reports can be found in rust-lang/rust#44494 and rust-lang/rust#28237). +- The resolutions of any unresolved questions if the stabilization + is for an RFC. ## FCP @@ -88,7 +90,7 @@ in the documentation. ### Updating the feature-gate listing There is a central listing of feature-gates in -`src/libsyntax/feature_gate.rs`. Search for the `declare_features!` +`[src/libsyntax/feature_gate.rs]`. Search for the `declare_features!` macro. There should be an entry for the feature you are aiming to stabilize, something like (this example is taken from [rust-lang/rust#32409]: @@ -171,6 +173,7 @@ if something { /* XXX */ } ``` [rust-lang/rust#32409]:https://github.com/rust-lang/rust/issues/32409 +[src/libsyntax/feature_gate.rs]:https://doc.rust-lang.org/nightly/nightly-rustc/syntax/feature_gate/index.html [The Reference]: https://github.com/rust-lang-nursery/reference [The Book]: https://github.com/rust-lang/book [Rust by Example]: https://github.com/rust-lang/rust-by-example diff --git a/src/walkthrough.md b/src/walkthrough.md index e77a0f690..fa259de99 100644 --- a/src/walkthrough.md +++ b/src/walkthrough.md @@ -260,10 +260,6 @@ about the feature. [stab]: https://github.com/rust-lang/rust/pull/56245 -TODO: currently, we have a [forge article][feature-stab] about stabilization, but -we really ought to move that to the guide (in fact, we probably should have a whole -chapter about feature gates and stabilization). - [feature-stab]: https://forge.rust-lang.org/stabilization-guide.html [relnotes]: https://github.com/rust-lang/rust/blob/master/RELEASES.md From a87018af25ad25737b6f4e00238ae3118b6b7818 Mon Sep 17 00:00:00 2001 From: Who? Me?! Date: Thu, 17 Jan 2019 16:40:07 -0500 Subject: [PATCH 13/15] Update src/stabilization_guide.md Co-Authored-By: rajcspsg --- src/stabilization_guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/stabilization_guide.md b/src/stabilization_guide.md index 7f3c7321a..c217c2251 100644 --- a/src/stabilization_guide.md +++ b/src/stabilization_guide.md @@ -33,7 +33,7 @@ Places that may need updated documentation: - [Rust by Example]: As needed. Prepare PRs to update documentations invovling this new feature -for repositories mentioned above.Maintainers of these repositories +for repositories mentioned above. Maintainers of these repositories will keep these PRs open until the whole stabilization process has completed. Meanwhile, we can proceed to the next step. From 91f453439e1fcb0274bf5b73622f82713198074f Mon Sep 17 00:00:00 2001 From: Who? Me?! Date: Thu, 17 Jan 2019 16:40:18 -0500 Subject: [PATCH 14/15] Update src/stabilization_guide.md Co-Authored-By: rajcspsg --- src/stabilization_guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/stabilization_guide.md b/src/stabilization_guide.md index c217c2251..6296aaa01 100644 --- a/src/stabilization_guide.md +++ b/src/stabilization_guide.md @@ -90,7 +90,7 @@ in the documentation. ### Updating the feature-gate listing There is a central listing of feature-gates in -`[src/libsyntax/feature_gate.rs]`. Search for the `declare_features!` +[`src/libsyntax/feature_gate.rs`]. Search for the `declare_features!` macro. There should be an entry for the feature you are aiming to stabilize, something like (this example is taken from [rust-lang/rust#32409]: From c110fabd9d3a994e83bf8b30b78a7b8e031e3f88 Mon Sep 17 00:00:00 2001 From: Rajkumar Natarajan Date: Thu, 17 Jan 2019 17:04:03 -0500 Subject: [PATCH 15/15] issue 130 stabilization guide --- src/stabilization_guide.md | 29 +++++++++++++++-------------- src/walkthrough.md | 4 +--- 2 files changed, 16 insertions(+), 17 deletions(-) diff --git a/src/stabilization_guide.md b/src/stabilization_guide.md index 6296aaa01..eb2c64298 100644 --- a/src/stabilization_guide.md +++ b/src/stabilization_guide.md @@ -12,7 +12,7 @@ following steps. ## Documentation PRs If any documentation for this feature exists, it should be -in the `Unstable Book`, located at `src/doc/unstable-book`. +in the [`Unstable Book`], located at [`src/doc/unstable-book`]. If it exists, the page for the feature gate should be removed. If there was documentation there, integrating it into the @@ -63,8 +63,7 @@ The report should contain: If any member of the team responsible for tracking this feature agrees with stabilizing this feature, they will -start the FCP (final-comment-period) process by -commenting +start the FCP (final-comment-period) process by commenting ```bash @rfcbot fcp merge @@ -75,24 +74,24 @@ decision is to stabilize, we proceed to do the actual code modification. ## Stabilization PR -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 you on a little tour -through the source code. +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 +you on a little tour through the source code. -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. +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. -Note: Before we stabilize any feature, it's the rule that it should appear -in the documentation. +Note: Before we stabilize any feature, it's the rule that it +should appear in the documentation. ### Updating the feature-gate listing There is a central listing of feature-gates in [`src/libsyntax/feature_gate.rs`]. Search for the `declare_features!` -macro. There should be an entry for the feature you are aiming to -stabilize, something like (this example is taken from +macro. There should be an entry for the feature you are aiming +to stabilize, something like (this example is taken from [rust-lang/rust#32409]: ```rust,ignore @@ -177,3 +176,5 @@ if something { /* XXX */ } [The Reference]: https://github.com/rust-lang-nursery/reference [The Book]: https://github.com/rust-lang/book [Rust by Example]: https://github.com/rust-lang/rust-by-example +[`Unstable Book`]: https://doc.rust-lang.org/unstable-book/index.html +[`src/doc/unstable-book`]: https://github.com/rust-lang/rust/tree/master/src/doc/unstable-book \ No newline at end of file diff --git a/src/walkthrough.md b/src/walkthrough.md index fa259de99..2823426be 100644 --- a/src/walkthrough.md +++ b/src/walkthrough.md @@ -258,8 +258,6 @@ After this, [a PR is made][stab] to remove the feature gate, enabling the featur default (on the 2018 edition). A note is added to the [Release notes][relnotes] about the feature. -[stab]: https://github.com/rust-lang/rust/pull/56245 - -[feature-stab]: https://forge.rust-lang.org/stabilization-guide.html +Steps to stabilize the feature can be found at [Stabilizing Features](./stabilization_guide.md). [relnotes]: https://github.com/rust-lang/rust/blob/master/RELEASES.md