src/doc/rustc-dev-guide/src/feature-gates.md

   1 # Feature Gates
   2
   3 This chapter is intended to provide basic help for adding, removing, and
   4 modifying feature gates.
   5
   6
   7 ## Adding a feature gate
   8
   9 See ["Stability in code"] for help with adding a new feature; this section just
  10 covers how to add the feature gate *declaration*.
  11
  12 Add a feature gate declaration to `rustc_feature/src/active.rs` in the active
  13 `declare_features` block:
  14
  15 ```rust,ignore
  16 /// description of feature
  17 (active, $feature_name, "$current_nightly_version", Some($tracking_issue_number), $edition)
  18 ```
  19
  20 where `$edition` has the type `Option<Edition>`, and is typically
  21 just `None`.
  22
  23 For example:
  24
  25 ```rust,ignore
  26 /// Allows defining identifiers beyond ASCII.
  27 (active, non_ascii_idents, "1.0.0", Some(55467), None),
  28 ```
  29
  30 When added, the current version should be the one for the current nightly.
  31 Once the feature is moved to `accepted.rs`, the version is changed to that
  32 nightly version.
  33
  34
  35 ## Removing a feature gate
  36
  37 [removing]: #removing-a-feature-gate
  38
  39 To remove a feature gate, follow these steps:
  40
  41 1. Remove the feature gate declaration in `rustc_feature/src/active.rs`.
  42    It will look like this:
  43
  44    ```rust,ignore
  45    /// description of feature
  46    (active, $feature_name, "$version", Some($tracking_issue_number), $edition)
  47    ```
  48
  49 2. Add a modified version of the feature gate declaration that you just
  50    removed to `rustc_feature/src/removed.rs`:
  51
  52    ```rust,ignore
  53    /// description of feature
  54    (removed, $old_feature_name, "$version", Some($tracking_issue_number), $edition,
  55     Some("$why_it_was_removed"))
  56    ```
  57
  58
  59 ## Renaming a feature gate
  60
  61 [renaming]: #renaming-a-feature-gate
  62
  63 To rename a feature gate, follow these steps (the first two are the same steps
  64 to follow when [removing a feature gate][removing]):
  65
  66 1. Remove the old feature gate declaration in `rustc_feature/src/active.rs`.
  67    It will look like this:
  68
  69    ```rust,ignore
  70    /// description of feature
  71    (active, $old_feature_name, "$version", Some($tracking_issue_number), $edition)
  72    ```
  73
  74 2. Add a modified version of the old feature gate declaration that you just
  75    removed to `rustc_feature/src/removed.rs`:
  76
  77    ```rust,ignore
  78    /// description of feature
  79    /// Renamed to `$new_feature_name`
  80    (removed, $old_feature_name, "$version", Some($tracking_issue_number), $edition,
  81     Some("renamed to `$new_feature_name`"))
  82    ```
  83
  84 3. Add a feature gate declaration with the new name to
  85    `rustc_feature/src/active.rs`. It should look very similar to the old
  86    declaration:
  87
  88    ```rust,ignore
  89    /// description of feature
  90    (active, $new_feature_name, "$version", Some($tracking_issue_number), $edition)
  91    ```
  92
  93
  94 ## Stabilizing a feature
  95
  96 See ["Updating the feature-gate listing"] in the "Stabilizing Features" chapter
  97 for instructions. There are additional steps you will need to take beyond just
  98 updating the declaration!
  99
 100
 101 ["Stability in code"]: ./implementing_new_features.md#stability-in-code
 102 ["Updating the feature-gate listing"]: ./stabilization_guide.md#updating-the-feature-gate-listing