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,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