diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 41de14954..62081cd56 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -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) diff --git a/src/feature-gates.md b/src/feature-gates.md new file mode 100644 index 000000000..db6c72ff8 --- /dev/null +++ b/src/feature-gates.md @@ -0,0 +1,102 @@ +# Feature Gates + +This chapter is intended to provide basic help for adding, removing, and +modifying feature gates. + + +## Adding a feature gate + +See ["Stability in code"] for help with adding a new feature; this section just +covers how to add the feature gate *declaration*. + +Add a feature gate declaration to `rustc_feature/src/active.rs` in the active +`declare_features` block: + +```rust,ignore +/// description of feature +(active, $feature_name, "$current_nightly_version", Some($tracking_issue_number), $edition) +``` + +where `$edition` has the type `Option`, and is typically +just `None`. + +For example: + +```rust,ignore +/// Allows defining identifiers beyond ASCII. +(active, non_ascii_idents, "1.0.0", Some(55467), None), +``` + +When added, the current version should be the one for the current nightly. +Once the feature is moved to `accepted.rs`, the version is changed to that +nightly version. + + +## 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) + ``` + + +## Stabilizing a feature + +See ["Updating the feature-gate listing"] in the "Stabilizing Features" chapter +for instructions. There are additional steps you will need to take beyond just +updating the declaration! + + +["Stability in code"]: ./implementing_new_features.md#stability-in-code +["Updating the feature-gate listing"]: ./stabilization_guide.md#updating-the-feature-gate-listing diff --git a/src/implementing_new_features.md b/src/implementing_new_features.md index baf4e2b51..3a65f15e7 100644 --- a/src/implementing_new_features.md +++ b/src/implementing_new_features.md @@ -127,25 +127,8 @@ a new unstable feature: in the RFC). 3. Add a feature gate declaration to `rustc_feature/src/active.rs` - in the active `declare_features` block: - - ```rust,ignore - /// description of feature - (active, $feature_name, "$current_nightly_version", Some($tracking_issue_number), $edition) - ``` - - where `$edition` has the type `Option`, and is typically - just `None`. - - For example: - - ```rust,ignore - /// Allows defining identifiers beyond ASCII. - (active, non_ascii_idents, "1.0.0", Some(55467), None), - ``` - - When added, the current version should be the one for the current nightly. - Once the feature is moved to `accepted.rs`, the version is changed to that nightly version. + in the active `declare_features` block. See [here][add-feature-gate] for + detailed instructions. 4. Prevent usage of the new feature unless the feature gate is set. You can check it in most places in the compiler using the @@ -182,3 +165,4 @@ a new unstable feature: [stability in code]: #stability-in-code [here]: ./stabilization_guide.md [tracking issue]: #tracking-issue +[add-feature-gate]: ./feature-gates.md#adding-a-feature-gate