issue_130_stabilization_guide

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)

src/stabilization_guide.md

@@ -0,0 +1,180 @@
+# 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
+
+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.
+
+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).
+- The resolutions of any unresolved questions if the stabilization
+  is for an RFC.
+
+## 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'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
+[rust-lang/rust#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:
+
+```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
+found by consulting [the forge](https://forge.rust-lang.org/), which will guide
+you the next stable release number. You want to add 1 to that,
+because the code that lands today will become go into beta on that
+date, and then become stable after that. So, at the time of this
+writing, the next stable release (i.e. what is currently beta) was
+1.30.0, hence I wrote 1.31.0 above.
+
+### 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 `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).
+
+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:
+
+```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
+now that `#[pub_restricted]` is stable.
+
+For more subtle features, you may find code like this:
+
+```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
+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 */`.
+
+```rust,ignore
+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 */ }
+```
+
+[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
+[`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

src/walkthrough.md

@@ -258,12 +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
-
-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
+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