Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

Commit 6578c56

Browse files
committed
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.
1 parent c242e57 commit 6578c56

File tree

2 files changed

+52
-47
lines changed

2 files changed

+52
-47
lines changed

‎src/feature-gates.md‎

Lines changed: 6 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -3,44 +3,16 @@
33
This chapter is intended to provide basic help for adding, removing, and
44
modifying feature gates.
55

6+
Note that this is specific to *language* feature gates; *library* feature gates use [a different
7+
mechanism][libs-gate].
68

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-
First, add the feature name to `rustc_span/src/symbol.rs` in the `Symbols {...}` block.
13-
14-
Then, add a feature gate declaration to `rustc_feature/src/active.rs` in the active
15-
`declare_features` block:
16-
17-
```rust,ignore
18-
/// description of feature
19-
(active, $feature_name, "$current_nightly_version", Some($tracking_issue_number), $edition)
20-
```
9+
[libs-gate]: ./stability.md
2110

22-
where `$edition` has the type `Option<Edition>`, and is typically
23-
just `None`.
24-
25-
For example:
26-
27-
```rust,ignore
28-
/// Allows defining identifiers beyond ASCII.
29-
(active, non_ascii_idents, "1.0.0", Some(55467), None),
30-
```
31-
32-
Features can be marked as incomplete, and trigger the warn-by-default [`incomplete_features` lint]
33-
by setting their type to `incomplete`:
34-
35-
```rust,ignore
36-
/// Allows unsized rvalues at arguments and parameters.
37-
(incomplete, unsized_locals, "1.30.0", Some(48055), None),
38-
```
11+
## Adding a feature gate
3912

40-
When added, the current version should be the one for the current nightly.
41-
Once the feature is moved to `accepted.rs`, the version is changed to that
42-
nightly version.
13+
See ["Stability in code"][adding] in the "Implementing new features" section for instructions.
4314

15+
[adding]: ./implementing_new_features.md#stability-in-code
4416

4517
## Removing a feature gate
4618

@@ -109,5 +81,4 @@ updating the declaration!
10981

11082

11183
["Stability in code"]: ./implementing_new_features.md#stability-in-code
112-
[`incomplete_features` lint]: https://doc.rust-lang.org/rustc/lints/listing/warn-by-default.html#incomplete-features
11384
["Updating the feature-gate listing"]: ./stabilization_guide.md#updating-the-feature-gate-listing

‎src/implementing_new_features.md‎

Lines changed: 46 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -128,14 +128,48 @@ a new unstable feature:
128128
The tracking issue should be labeled with at least `C-tracking-issue`.
129129
For a language feature, a label `F-feature_name` should be added as well.
130130

131-
2. Pick a name for the feature gate (for RFCs, use the name
131+
1. Pick a name for the feature gate (for RFCs, use the name
132132
in the RFC).
133133

134-
3. Add a feature gate declaration to `rustc_feature/src/active.rs` in the active
135-
`declare_features` block, and add the feature gate keyword to
136-
`rustc_span/src/symbol.rs`. See [here][add-feature-gate] for detailed instructions.
134+
1. Add the feature name to `rustc_span/src/symbol.rs` in the `Symbols {...}` block.
137135

138-
4. Prevent usage of the new feature unless the feature gate is set.
136+
1. Add a feature gate declaration to `rustc_feature/src/active.rs` in the active
137+
`declare_features` block.
138+
139+
```rust ignore
140+
/// description of feature
141+
(active, $feature_name, "CURRENT_RUSTC_VERSION", Some($tracking_issue_number), $edition)
142+
```
143+
144+
where `$edition` has the type `Option<Edition>`, and is typically just `None`. If you haven't yet
145+
opened a tracking issue (e.g. because you want initial feedback on whether the feature is likely
146+
to be accepted), you can temporarily use `None` - but make sure to update it before the PR is
147+
merged!
148+
149+
For example:
150+
151+
```rust ignore
152+
/// Allows defining identifiers beyond ASCII.
153+
(active, non_ascii_idents, "CURRENT_RUSTC_VERSION", Some(55467), None),
154+
```
155+
156+
Features can be marked as incomplete, and trigger the warn-by-default [`incomplete_features`
157+
lint]
158+
by setting their type to `incomplete`:
159+
160+
[`incomplete_features` lint]: https://doc.rust-lang.org/rustc/lints/listing/warn-by-default.html#incomplete-features
161+
162+
```rust ignore
163+
/// Allows unsized rvalues at arguments and parameters.
164+
(incomplete, unsized_locals, "CURRENT_RUSTC_VERSION", Some(48055), None),
165+
```
166+
167+
To avoid [semantic merge conflicts], please use `CURRENT_RUSTC_VERSION` instead of `1.70` or
168+
another explicit version number.
169+
170+
[semantic merge conflicts]: https://bors.tech/essay/2017/02/02/pitch/
171+
172+
1. Prevent usage of the new feature unless the feature gate is set.
139173
You can check it in most places in the compiler using the
140174
expression `tcx.features().$feature_name` (or
141175
`sess.features_untracked().$feature_name` if the
@@ -151,18 +185,18 @@ a new unstable feature:
151185
and then finally feature-gate all the spans in
152186
[`rustc_ast_passes::feature_gate::check_crate`].
153187

154-
5. Add a test to ensure the feature cannot be used without
155-
a feature gate, by creating `feature-gate-$feature_name.rs`
156-
and `feature-gate-$feature_name.stderr` files under the
157-
directory where the other tests for your feature reside.
188+
1. Add a test to ensure the feature cannot be used without
189+
a feature gate, by creating `tests/ui/feature-gates/feature-gate-$feature_name.rs`.
190+
You can generate the corresponding `.stderr` file by running `./x.py test tests/ui/feature-gates/
191+
--bless`.
158192

159-
6. Add a section to the unstable book, in
193+
1. Add a section to the unstable book, in
160194
`src/doc/unstable-book/src/language-features/$feature_name.md`.
161195

162-
7. Write a lot of tests for the new feature.
196+
1. Write a lot of tests for the new feature, preferably in `tests/ui/$feature_name/`.
163197
PRs without tests will not be accepted!
164198

165-
8. Get your PR reviewed and land it. You have now successfully
199+
1. Get your PR reviewed and land it. You have now successfully
166200
implemented a feature in Rust!
167201

168202
[`GatedSpans`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_session/parse/struct.GatedSpans.html

0 commit comments

Comments
(0)

AltStyle によって変換されたページ (->オリジナル) /