Improve feature gate and x.py docs

src/SUMMARY.md

@@ -40,12 +40,12 @@
 - [Using Git](./git.md)
 - [Mastering @rustbot](./rustbot.md)
 - [Walkthrough: a typical contribution](./walkthrough.md)
-- [Procedures for Breaking Changes](./bug-fix-procedure.md)
-- [Implementing new features](./implementing_new_features.md)
+- [Implementing new language features](./implementing_new_features.md)
 - [Stability attributes](./stability.md)
 - [Stabilizing Features](./stabilization_guide.md)
 - [Feature Gates](./feature-gates.md)
 - [Coding conventions](./conventions.md)
+- [Procedures for Breaking Changes](./bug-fix-procedure.md)
 - [Using external repositories](./external-repos.md)
 - [Fuzzing](./fuzzing.md)
 - [Notification groups](notification-groups/about.md)

src/building/how-to-build-and-run.md

@@ -57,7 +57,50 @@ if you want to learn more about `x.py`, [read this chapter][bootstrap].
 
 [bootstrap]: ./bootstrapping.md
 
-### Running `x.py` slightly more conveniently
+### Running `x.py`
+
+The `x.py` command can be run directly on most Unix systems in the following format:
+
+```sh
+./x.py <subcommand> [flags]
+```
+
+This is how the documentation and examples assume you are running `x.py`.
+Some alternative ways are:
+
+```sh
+# On a Unix shell if you don't have the necessary `python3` command
+./x <subcommand> [flags]
+
+# In Windows Powershell (if powershell is configured to run scripts)
+./x <subcommand> [flags]
+./x.ps1 <subcommand> [flags]
+
+# On the Windows Command Prompt (if .py files are configured to run Python)
+x.py <subcommand> [flags]
+
+# You can also run Python yourself, e.g.:
+python x.py <subcommand> [flags]
+```
+
+On Windows, the Powershell commands may give you an error that looks like this:
+```
+PS C:\Users\vboxuser\rust> ./x
+./x : File C:\Users\vboxuser\rust\x.ps1 cannot be loaded because running scripts is disabled on this system. For more
+information, see about_Execution_Policies at https:/go.microsoft.com/fwlink/?LinkID=135170.
+At line:1 char:1
++ ./x
++ ~~~
+    + CategoryInfo          : SecurityError: (:) [], PSSecurityException
+    + FullyQualifiedErrorId : UnauthorizedAccess
+```
+
+You can avoid this error by allowing powershell to run local scripts:
+```
+Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
+```
+
+#### Running `x.py` slightly more conveniently
 
 There is a binary that wraps `x.py` called `x` in `src/tools/x`. All it does is
 run `x.py`, but it can be installed system-wide and run from any subdirectory

src/feature-gates.md

@@ -3,44 +3,16 @@
 This chapter is intended to provide basic help for adding, removing, and
 modifying feature gates.
 
+Note that this is specific to *language* feature gates; *library* feature gates use [a different
+mechanism][libs-gate].
 
-## 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*.
-
-First, add the feature name to `rustc_span/src/symbol.rs` in the `Symbols {...}` block.
-
-Then, 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)
-```
+[libs-gate]: ./stability.md
 
-where `$edition` has the type `Option<Edition>`, and is typically
-just `None`.
-
-For example:
-
-```rust,ignore
-/// Allows defining identifiers beyond ASCII.
-(active, non_ascii_idents, "1.0.0", Some(55467), None),
-```
-
-Features can be marked as incomplete, and trigger the warn-by-default [`incomplete_features` lint]
-by setting their type to `incomplete`:
-
-```rust,ignore
-/// Allows unsized rvalues at arguments and parameters.
-(incomplete, unsized_locals, "1.30.0", Some(48055), None),
-```
+## Adding a feature gate
 
-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.
+See ["Stability in code"][adding] in the "Implementing new features" section for instructions.
 
+[adding]: ./implementing_new_features.md#stability-in-code
 
 ## Removing a feature gate
 
@@ -109,5 +81,4 @@ updating the declaration!
 
 
 ["Stability in code"]: ./implementing_new_features.md#stability-in-code
-[`incomplete_features` lint]: https://doc.rust-lang.org/rustc/lints/listing/warn-by-default.html#incomplete-features
 ["Updating the feature-gate listing"]: ./stabilization_guide.md#updating-the-feature-gate-listing

src/implementing_new_features.md

@@ -1,11 +1,16 @@
-# Implementing new features
+# Implementing new language features
 
 <!-- toc -->
 
 When you want to implement a new significant feature in the compiler,
 you need to go through this process to make sure everything goes
 smoothly.
 
+**NOTE: this section is for *language* features, not *library* features, which use [a different
+*process].**
+
+[a different process]: ./stability.md
+
 ## The @rfcbot FCP process
 
 When the change is small and uncontroversial, then it can be done
@@ -91,31 +96,16 @@ by being unstable and unchanged for a year.
 To keep track of the status of an unstable feature, the
 experience we get while using it on nightly, and of the
 concerns that block its stabilization, every feature-gate
-needs a tracking issue.
-
-General discussions about the feature should be done on
-the tracking issue.
+needs a tracking issue. General discussions about the feature should be done on the tracking issue.
 
 For features that have an RFC, you should use the RFC's
 tracking issue for the feature.
 
 For other features, you'll have to make a tracking issue
 for that feature. The issue title should be "Tracking issue
-for YOUR FEATURE".
-
-For tracking issues for features (as opposed to future-compat
-warnings), I don't think the description has to contain
-anything specific. Generally we put the list of items required
-for stabilization in a checklist, e.g.,
+for YOUR FEATURE". Use the ["Tracking Issue" issue template][template].
 
-```txt
-**Steps:**
-
-- [ ] Implement the RFC. (CC @rust-lang/compiler -- can anyone write
-      up mentoring instructions?)
-- [ ] Adjust the documentation. ([See instructions on rustc-dev-guide.](stabilization_guide.md#documentation-prs))
-- [ ] Stabilize the feature. ([See instructions on rustc-dev-guide.](stabilization_guide.md#stabilization-pr))
-```
+[template]: https://github.com/rust-lang/rust/issues/new?template=tracking_issue.md
 
 ##  Stability in code
 
@@ -128,14 +118,48 @@ a new unstable feature:
    The tracking issue should be labeled with at least `C-tracking-issue`.
    For a language feature, a label `F-feature_name` should be added as well.
 
-2. Pick a name for the feature gate (for RFCs, use the name
+1. Pick a name for the feature gate (for RFCs, use the name
    in the RFC).
 
-3. Add a feature gate declaration to `rustc_feature/src/active.rs` in the active
-   `declare_features` block, and add the feature gate keyword to
-   `rustc_span/src/symbol.rs`. See [here][add-feature-gate] for detailed instructions.
+1. Add the feature name to `rustc_span/src/symbol.rs` in the `Symbols {...}` block.
+
+1. 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_RUSTC_VERSION", Some($tracking_issue_number), $edition)
+   ```
+
+   where `$edition` has the type `Option<Edition>`, and is typically just `None`. If you haven't yet
+   opened a tracking issue (e.g. because you want initial feedback on whether the feature is likely
+   to be accepted), you can temporarily use `None` - but make sure to update it before the PR is
+   merged!
+
+   For example:
+
+   ```rust ignore
+   /// Allows defining identifiers beyond ASCII.
+   (active, non_ascii_idents, "CURRENT_RUSTC_VERSION", Some(55467), None),
+   ```
+
+   Features can be marked as incomplete, and trigger the warn-by-default [`incomplete_features`
+   lint]
+   by setting their type to `incomplete`:
+
+   [`incomplete_features` lint]: https://doc.rust-lang.org/rustc/lints/listing/warn-by-default.html#incomplete-features
+
+   ```rust ignore
+   /// Allows unsized rvalues at arguments and parameters.
+   (incomplete, unsized_locals, "CURRENT_RUSTC_VERSION", Some(48055), None),
+   ```
+
+   To avoid [semantic merge conflicts], please use `CURRENT_RUSTC_VERSION` instead of `1.70` or
+   another explicit version number.
+
+   [semantic merge conflicts]: https://bors.tech/essay/2017/02/02/pitch/
 
-4. Prevent usage of the new feature unless the feature gate is set.
+1. Prevent usage of the new feature unless the feature gate is set.
    You can check it in most places in the compiler using the
    expression `tcx.features().$feature_name` (or
    `sess.features_untracked().$feature_name` if the
@@ -151,18 +175,18 @@ a new unstable feature:
    and then finally feature-gate all the spans in
    [`rustc_ast_passes::feature_gate::check_crate`].
 
-5. Add a test to ensure the feature cannot be used without
-   a feature gate, by creating `feature-gate-$feature_name.rs`
-   and `feature-gate-$feature_name.stderr` files under the
-   directory where the other tests for your feature reside.
+1. Add a test to ensure the feature cannot be used without
+   a feature gate, by creating `tests/ui/feature-gates/feature-gate-$feature_name.rs`.
+   You can generate the corresponding `.stderr` file by running `./x.py test tests/ui/feature-gates/
+   --bless`.
 
-6. Add a section to the unstable book, in
+1. Add a section to the unstable book, in
    `src/doc/unstable-book/src/language-features/$feature_name.md`.
 
-7. Write a lot of tests for the new feature.
+1. Write a lot of tests for the new feature, preferably in `tests/ui/$feature_name/`.
    PRs without tests will not be accepted!
 
-8. Get your PR reviewed and land it. You have now successfully
+1. Get your PR reviewed and land it. You have now successfully
    implemented a feature in Rust!
 
 [`GatedSpans`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_session/parse/struct.GatedSpans.html
@@ -172,5 +196,5 @@ a new unstable feature:
 [value the stability of Rust]: https://github.com/rust-lang/rfcs/blob/master/text/1122-language-semver.md
 [stability in code]: #stability-in-code
 [here]: ./stabilization_guide.md
-[tracking issue]: #tracking-issue
+[tracking issue]: #tracking-issues
 [add-feature-gate]: ./feature-gates.md#adding-a-feature-gate

src/stability.md

@@ -1,12 +1,12 @@
 # Stability attributes
 
-<!-- toc -->
-
 This section is about the stability attributes and schemes that allow stable
 APIs to use unstable APIs internally in the rustc standard library.
 
-For instructions on stabilizing a language feature see [Stabilizing
-Features](./stabilization_guide.md).
+**NOTE**: this section is for *library* features, not *language* features. For instructions on
+stabilizing a language feature see [Stabilizing Features](./stabilization_guide.md).
+
+<!-- toc -->
 
 ## unstable
 

src/stabilization_guide.md

@@ -1,6 +1,6 @@
 # Request for stabilization
 
-**NOTE**: this page is about stabilizing language features.
+**NOTE**: this page is about stabilizing *language* features.
 For stabilizing *library* features, see [Stabilizing a library feature].
 
 [Stabilizing a library feature]: ./stability.md#stabilizing-a-library-feature