Document how to modify feature gates

How to remove them and how to rename them.

cc <https://github.com/rust-lang/rust/pull/79336#discussion_r528627318>
cc @varkor
This commit is contained in:
Camelid 2020-11-23 14:37:10 -08:00 committed by Joshua Nelson
parent c63305c6e8
commit ea6df8f903
2 changed files with 66 additions and 0 deletions

View File

@ -38,6 +38,7 @@
- [Implementing new features](./implementing_new_features.md)
- [Stability attributes](./stability.md)
- [Stabilizing Features](./stabilization_guide.md)
- [Feature Gates](./feature-gates.md)
- [Coding conventions](./conventions.md)
- [Notification groups](notification-groups/about.md)
- [ARM](notification-groups/arm.md)

65
src/feature-gates.md Normal file
View File

@ -0,0 +1,65 @@
# Feature Gates
This chapter is intended to provide basic help for modifying feature gates. See
["Stability in code"][stability-section] for help with *adding* feature gates.
[stability-section]: ./implementing_new_features.md#stability-in-code
## Removing a feature gate
[removing]: #removing-a-feature-gate
To remove a feature gate, follow these steps:
1. Remove the feature gate declaration in `rustc_feature/src/active.rs`.
It will look like this:
```rust,ignore
/// description of feature
(active, $feature_name, "$version", Some($tracking_issue_number), $edition)
```
2. Add a modified version of the feature gate declaration that you just
removed to `rustc_feature/src/removed.rs`:
```rust,ignore
/// description of feature
(removed, $old_feature_name, "$version", Some($tracking_issue_number), $edition,
Some("$why_it_was_removed"))
```
## Renaming a feature gate
[renaming]: #renaming-a-feature-gate
To rename a feature gate, follow these steps (the first two are the same steps
to follow when [removing a feature gate][removing]):
1. Remove the old feature gate declaration in `rustc_feature/src/active.rs`.
It will look like this:
```rust,ignore
/// description of feature
(active, $old_feature_name, "$version", Some($tracking_issue_number), $edition)
```
2. Add a modified version of the old feature gate declaration that you just
removed to `rustc_feature/src/removed.rs`:
```rust,ignore
/// description of feature
/// Renamed to `$new_feature_name`
(removed, $old_feature_name, "$version", Some($tracking_issue_number), $edition,
Some("renamed to `$new_feature_name`"))
```
3. Add a feature gate declaration with the new name to
`rustc_feature/src/active.rs`. It should look very similar to the old
declaration:
```rust,ignore
/// description of feature
(active, $new_feature_name, "$version", Some($tracking_issue_number), $edition)
```