From 51fe17f7f50be52c87fa65aef7e55669715e0e63 Mon Sep 17 00:00:00 2001 From: jyn Date: Sat, 24 Jun 2023 10:37:06 -0500 Subject: [PATCH 1/7] Move "Adding a new feature gate" to the "Implementing new features" chapter Splitting the two was confusing and meant that similar information was in wildly different parts of the guide. Combine them into a single page. --- src/feature-gates.md | 41 ++++------------------ src/implementing_new_features.md | 58 +++++++++++++++++++++++++------- 2 files changed, 52 insertions(+), 47 deletions(-) diff --git a/src/feature-gates.md b/src/feature-gates.md index 9e9a83ea6..8ad4fea1f 100644 --- a/src/feature-gates.md +++ b/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`, 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 diff --git a/src/implementing_new_features.md b/src/implementing_new_features.md index 946637d29..a91375ce1 100644 --- a/src/implementing_new_features.md +++ b/src/implementing_new_features.md @@ -128,14 +128,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. -4. Prevent usage of the new feature unless the feature gate is set. +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`, 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/ + +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 +185,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 From dd6a8506ad6626e5f0c3c9570e29385003fae41b Mon Sep 17 00:00:00 2001 From: jyn Date: Sat, 24 Jun 2023 10:52:57 -0500 Subject: [PATCH 2/7] distinguish language and library processes more consistently --- src/SUMMARY.md | 2 +- src/implementing_new_features.md | 7 ++++++- src/stability.md | 8 ++++---- src/stabilization_guide.md | 2 +- 4 files changed, 12 insertions(+), 7 deletions(-) diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 9f7c9cf1b..9e13adf15 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -41,7 +41,7 @@ - [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) diff --git a/src/implementing_new_features.md b/src/implementing_new_features.md index a91375ce1..3d738dbe3 100644 --- a/src/implementing_new_features.md +++ b/src/implementing_new_features.md @@ -1,4 +1,4 @@ -# Implementing new features +# Implementing new language features @@ -6,6 +6,11 @@ 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 diff --git a/src/stability.md b/src/stability.md index 85c75fadb..bf82d8517 100644 --- a/src/stability.md +++ b/src/stability.md @@ -1,12 +1,12 @@ # Stability attributes - - 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). + + ## unstable diff --git a/src/stabilization_guide.md b/src/stabilization_guide.md index 0ac19293b..001ed25a5 100644 --- a/src/stabilization_guide.md +++ b/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 From 8c6a337c8805ce5ad1166d843bdb2c4dd1ae9947 Mon Sep 17 00:00:00 2001 From: jyn Date: Sat, 24 Jun 2023 10:53:00 -0500 Subject: [PATCH 3/7] move the Breaking Changes section later in the guide --- src/SUMMARY.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 9e13adf15..94e619f42 100644 --- a/src/SUMMARY.md +++ b/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 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) From cfe20464297d8cbbcdb5580992717fc29089573a Mon Sep 17 00:00:00 2001 From: jyn Date: Sat, 24 Jun 2023 10:54:11 -0500 Subject: [PATCH 4/7] fix broken link --- src/implementing_new_features.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/implementing_new_features.md b/src/implementing_new_features.md index 3d738dbe3..9ff642a6c 100644 --- a/src/implementing_new_features.md +++ b/src/implementing_new_features.md @@ -211,5 +211,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 From 19c7c863bf1daa5a03e8f8c26e098a0f39d277f6 Mon Sep 17 00:00:00 2001 From: jyn Date: Sat, 24 Jun 2023 10:58:44 -0500 Subject: [PATCH 5/7] cleanup the "tracking issue" section mostly this just suggests using a tracking issue instead of inlining the info from the issue template --- src/implementing_new_features.md | 21 +++------------------ 1 file changed, 3 insertions(+), 18 deletions(-) diff --git a/src/implementing_new_features.md b/src/implementing_new_features.md index 9ff642a6c..447b621da 100644 --- a/src/implementing_new_features.md +++ b/src/implementing_new_features.md @@ -96,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., - -```txt -**Steps:** +for YOUR FEATURE". Use the ["Tracking Issue" issue template][template]. -- [ ] 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 From 8e116521d7e15710c9e4023da9d315ccb4fc7f92 Mon Sep 17 00:00:00 2001 From: jyn Date: Sat, 24 Jun 2023 11:12:40 -0500 Subject: [PATCH 6/7] Inline alternate x.py invocations from the rust-lang/rust readme I'm going to make a follow-up PR shortly linking from rust-lang/rust to the dev guide so this info isn't duplicated. --- src/building/how-to-build-and-run.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/src/building/how-to-build-and-run.md b/src/building/how-to-build-and-run.md index 6444aab5f..92f44db44 100644 --- a/src/building/how-to-build-and-run.md +++ b/src/building/how-to-build-and-run.md @@ -57,6 +57,31 @@ if you want to learn more about `x.py`, [read this chapter][bootstrap]. [bootstrap]: ./bootstrapping.md +### Running `x.py` + +The `x.py` command can be run directly on most Unix systems in the following format: + +```sh +./x.py [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 [flags] + +# On Windows (if powershell is configured to run scripts) +./x.ps1 [flags] + +# On the Windows Command Prompt (if .py files are configured to run Python) +x.py [flags] + +# You can also run Python yourself, e.g.: +python x.py [flags] +``` + ### Running `x.py` slightly more conveniently There is a binary that wraps `x.py` called `x` in `src/tools/x`. All it does is From 5f5394fb41cd16f1da3f33528eec1c2e336c01b4 Mon Sep 17 00:00:00 2001 From: jyn Date: Sat, 24 Jun 2023 13:39:46 -0500 Subject: [PATCH 7/7] Improve Windows docs --- src/building/how-to-build-and-run.md | 22 ++++++++++++++++++++-- 1 file changed, 20 insertions(+), 2 deletions(-) diff --git a/src/building/how-to-build-and-run.md b/src/building/how-to-build-and-run.md index 92f44db44..14cad7867 100644 --- a/src/building/how-to-build-and-run.md +++ b/src/building/how-to-build-and-run.md @@ -72,7 +72,8 @@ Some alternative ways are: # On a Unix shell if you don't have the necessary `python3` command ./x [flags] -# On Windows (if powershell is configured to run scripts) +# In Windows Powershell (if powershell is configured to run scripts) +./x [flags] ./x.ps1 [flags] # On the Windows Command Prompt (if .py files are configured to run Python) @@ -82,7 +83,24 @@ x.py [flags] python x.py [flags] ``` -### Running `x.py` slightly more conveniently +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