add E-needs-test walkthrough

book.toml

@@ -96,3 +96,4 @@ warning-policy = "error"
 "/ty_module/instantiating_binders.html" = "/ty-module/instantiating-binders.html"
 "/ty_module/param_ty_const_regions.html" = "/ty-module/param-ty-const-regions.html"
 "/typing_parameter_envs.html" = "typing-parameter-envs.html"
+"/walkthrough.html" = "walkthroughs/test.html"

src/SUMMARY.md

@@ -57,13 +57,14 @@
 - [Running LLMs](./llm-guidance.md)
     - [Writing code with LLMs](./llm-guidance/writing.md)
     - [Reviewing code with LLMs](./llm-guidance/reviewing.md)
-- [Walkthrough: a typical contribution](./walkthrough.md)
+- [Walkthrough: adding a new test](./walkthroughs/test.md)
 - [Implementing new language features](./implementing-new-features.md)
 - [Stability guarantees](./stability-guarantees.md)
 - [Stability attributes](./stability.md)
 - [Stabilizing language features](./stabilization-guide.md)
     - [Stabilization report template](./stabilization-report-template.md)
 - [Feature Gates](./feature-gates.md)
+- [Walkthrough: a new language feature, from design to stabilization](./walkthroughs/lang-feature.md)
 - [Coding conventions](./conventions.md)
 - [Procedures for breaking changes](./bug-fix-procedure.md)
 - [Using external repositories](./external-repos.md)

src/walkthrough.md → src/walkthroughs/lang-feature.md

@@ -1,14 +1,7 @@
-# Walkthrough: a typical contribution
+# Walkthrough: a new language feature, from design to stabilization
 
-There are _a lot_ of ways to contribute to the Rust compiler, including fixing
-bugs, improving performance, helping design features, providing feedback on existing features, etc.
-This chapter does not claim to scratch the surface.
-Instead, it walks through the design and implementation of a new feature.
-Not all of the steps and processes described here are needed for every
-contribution, and I will try to point those out as they arise.
-
-In general, if you are interested in making a contribution and aren't sure
-where to start, please feel free to ask!
+This chapter walks through the design and implementation of a new language feature.
+Some of these steps are specific to language features, but many also extend to library features.
 
 ## Overview
 
@@ -244,7 +237,7 @@ There are a couple of things that may happen for some PRs during the review proc
   some merge conflicts with other PRs that happen to get merged first.
   You should fix these merge conflicts using the normal git procedures.
 
-[crater]: ./tests/crater.md
+[crater]: ../tests/crater.md
 
 If you are not doing a new feature or something like that (e.g. if you are
 fixing a bug), then that's it!
@@ -293,6 +286,6 @@ A note is added to the [Release notes][relnotes] about the feature.
 
 [stab]: https://github.com/rust-lang/rust/pull/56245
 
-Steps to stabilize the feature can be found at [Stabilizing Features](./stabilization-guide.md).
+Steps to stabilize the feature can be found at [Stabilizing Features](../stabilization-guide.md).
 
 [relnotes]: https://github.com/rust-lang/rust/blob/HEAD/RELEASES.md

src/walkthroughs/test.md

@@ -0,0 +1,135 @@
+# Walkthrough: adding a new test
+
+This chapter gives an example of a small change that you could make as your first contribution to Rust,
+using [rust#59333] and [rust#161442] as an example.
+
+[rust#59333]: https://github.com/rust-lang/rust/issues/59333
+[rust#161442]: https://github.com/rust-lang/rust/issues/161442
+
+## Find an `E-needs-test` issue to work on
+
+See ["What should I work on?"](../getting-started.md#What-should-I-work-on) for a list of possible tasks you could try out.
+Here, we've chosen an `E-needs-test` issue: 
+[rust#59333](https://github.com/rust-lang/rust/issues/59333).
+This is an especially good fit because it has an example
+[directly in the issue](https://github.com/rust-lang/rust/issues/59333#issuecomment-555973113),
+without needing additional work from you to minimize the bug.
+Of course, it's always very helpful for you to take `E-needs-test` that *doesn't* have a minimal example and create one.
+
+## Reproduce the issue
+
+The example here was posted in 2019, fully 7 years ago (at time of writing).
+Quite a lot of things change in the compiler in that period of time.
+To make sure the test is still accurate, *reproduce it with the most recent compiler*.
+An easy way to do this is with [play.rust-lang.org](https://play.rust-lang.org/?version=nightly) on the `nightly` branch,
+or [rust.godbolt.org](https://rust.godbolt.org/) with `rustc nightly`.
+You can also use `rustc +nightly` locally if you need complicated setup that isn't possible on Playground.
+
+## Convert the issue to a test
+
+Check out and set up the `rust-lang/rust` repo, as documented in [Quickstart](../building/quickstart.md):
+
+```console
+$ git clone https://github.com/rust-lang/rust
+$ cd rust
+$ ./x setup compiler
+$ ./x build library
+```
+
+Here, we use `compiler` as the default profile, since the bug we're fixing is related to the compiler.
+If you're adding a unit test to the standard library, you'd use `./x setup library`.
+
+This will also suggest setting up a [`.git/hooks/pre-push` check][pre-push].
+This is optional, but recommended.
+
+[pre-push]: ../building/suggested.md#installing-a-pre-push-hook
+
+We also started a build in the background with `./x build library`.
+Rust unfortunately takes quite a while to build,
+so starting a build early lets it run in the background while you're working on other things.
+
+See [UI tests](../tests/ui.md) for a guide on adding new tests.
+In rare cases, you may need a [run-make](../tests/compiletest.md#run-make-tests) or even more specialized kind of test.
+See [Compiletest](../tests/compiletest.md) for more information.
+
+In our case, our test is fairly simple:
+
+```rust
+// Save this file to `tests/ui/lint/dead-code/type-alias-used-in-impl-59333.rs`.
+
+//@ check-pass
+//! Regression test for <https://github.com/rust-lang/rust/issues/59333>.
+//! A type alias used only as (part of) the self type of an impl was
+//! incorrectly flagged as dead code.
+
+#![deny(dead_code)]
+
+struct Runner;
+
+type RuntimeImpl = Runner;
+
+trait Runtime {
+    fn run(&mut self);
+}
+
+impl Runtime for &mut RuntimeImpl {
+    fn run(&mut self) {}
+}
+
+struct Walker;
+
+type WalkerImpl = Walker;
+
+trait Walk {
+    fn walk(&self) {}
+}
+
+impl Walk for WalkerImpl {}
+
+fn main() {
+    let mut runner = Runner;
+    (&mut runner).run();
+    Walker.walk();
+}
+```
+
+Most of the details here don't matter too much, but note the `//@ check-pass` and `#![deny(dead_code)]` at the top.
+Together, those ensure that the compiler doesn't emit a `dead_code` lint when compiling this file.
+
+Also note the "Regression test for ..." comment.
+This is *very* helpful for your reviewer, since it helps them understand what the test is doing and whether there's a simpler way to test the behavior.
+Please do your best to write a complete description for the test.
+
+Run your test.
+[rust#161442] named its test `tests/ui/lint/dead-code/type-alias-used-in-impl-59333.rs`,
+so you could run:
+
+```
+./x test tests/ui/lint/dead-code/type-alias-used-in-impl-59333.rs
+```
+
+If that passes, your test is ready.
+
+## Open a PR
+
+Follow the instructions in [Using Git](../git.md):
+
+First, run the pre-push check if you didn't set it up earlier:
+
+```sh
+./x test tidy
+```
+
+Then, [open the PR](https://guides.github.com/activities/forking/#making-a-pull-request):
+
+```
+git switch --create issue-59333-test
+git add tests/ui/lint/dead-code/type-alias-used-in-impl-59333.rs
+git commit
+git remote add personal https://github.com/YOUR_USERNAME_HERE/rust.git
+git push --set-upstream personal issue-59333-test
+```
+
+## Review and feedback
+
+See [Opening a PR](../git.md#opening-a-pr).