issue_130_stabilization_guide
This commit is contained in:
Rajkumar Natarajan
Who? Me?!
parent
2e56207594
commit
69005b5daa
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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
|
||||
Loading…
Reference in New Issue