From 72eca8fcc517033d5d6b6c1e60ff3008bb4edc34 Mon Sep 17 00:00:00 2001
From: Camelid <camelidcamel@gmail.com>
Date: Mon, 23 Nov 2020 14:37:10 -0800
Subject: [PATCH] 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
---
 src/SUMMARY.md       |  1 +
 src/feature-gates.md | 65 ++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 66 insertions(+)
 create mode 100644 src/feature-gates.md

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..b4aae0443
--- /dev/null
+++ b/src/feature-gates.md
@@ -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)
+   ```