From 69005b5daaced57870b9a8f9b9bc6af4c9f5fe00 Mon Sep 17 00:00:00 2001 From: Rajkumar Natarajan Date: Tue, 15 Jan 2019 17:07:06 -0500 Subject: [PATCH] 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 bfb112ce..9bdf8927 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 00000000..af86b450 --- /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