|
| 1 | +# Cleanup Crew |
| 2 | + |
| 3 | +**Github Label:** [ICEBreaker-Cleanup-Crew] |
| 4 | + |
| 5 | +[ICEBreaker-Cleanup-Crew]: https://github.com/rust-lang/rust/labels/ICEBreaker-Cleanup-Crew |
| 6 | + |
| 7 | +The "Cleanup Crew" are focused on improving bug reports. Specifically, |
| 8 | +the goal is to try to ensure that every bug report has all the |
| 9 | +information that will be needed for someone to fix it: |
| 10 | + |
| 11 | +* a minimal, standalone example that shows the problem |
| 12 | +* links to duplicates or related bugs |
| 13 | +* if the bug is a regression (something that used to work, but no longer does), |
| 14 | + then a bisection to the PR or nightly that caused the regression |
| 15 | + |
| 16 | +This kind of cleanup is invaluable in getting bugs fixed. Better |
| 17 | +still, it can be done by anybody who knows Rust, without any |
| 18 | +particularly deep knowledge of the compiler. |
| 19 | + |
| 20 | +Let's look a bit at the workflow for doing "cleanup crew" actions. |
| 21 | + |
| 22 | +## Finding a minimal, standalone example |
| 23 | + |
| 24 | +Here the ultimate goal is to produce an example that reproduces the same |
| 25 | +problem but without relying on any external crates. Such a test ought to contain |
| 26 | +as little code as possible, as well. This will make it much easier to isolate the problem. |
| 27 | + |
| 28 | +However, even if the "ultimate minimal test" cannot be achieved, it's |
| 29 | +still useful to post incremental minimizations. For example, if you |
| 30 | +can eliminate some of the external dependencies, that is helpful, and |
| 31 | +so forth. |
| 32 | + |
| 33 | +It's particularly useful to reduce to an example that works |
| 34 | +in the [Rust playground](https://play.rust-lang.org/), rather than |
| 35 | +requiring people to checkout a cargo build. |
| 36 | + |
| 37 | +There are many resources for how to produce minimized test cases. Here |
| 38 | +are a few: |
| 39 | + |
| 40 | +* The [rust-reduce](https://github.com/jethrogb/rust-reduce) tool can try to reduce |
| 41 | + code automatically. |
| 42 | + * The [C-reduce](https://embed.cs.utah.edu/creduce/) tool also works |
| 43 | + on Rust code, though it requires that you start from a single |
| 44 | + file. (XXX link to some post explaining how to do it?) |
| 45 | +* pnkfelix's [Rust Bug Minimization Patterns] blog post |
| 46 | + * This post focuses on "heavy bore" techniques, where you are |
| 47 | + starting with a large, complex cargo project that you wish to |
| 48 | + narrow down to something standalone. |
| 49 | + |
| 50 | +[Rust Bug Minimization Patterns]: http://blog.pnkfx.org/blog/2019/11/18/rust-bug-minimization-patterns/ |
| 51 | + |
| 52 | +## Links to duplicate or related bugs |
| 53 | + |
| 54 | +If you are on the "Cleanup Crew", you will sometimes see multiple bug |
| 55 | +reports that seem very similar. You can link one to the other just by |
| 56 | +mentioning the other bug number in a Github comment. Sometimes it is |
| 57 | +useful to close duplicate bugs. But if you do so, you should always |
| 58 | +copy any test case from the bug you are closing to the other bug that |
| 59 | +remains open, as sometimes duplicate-looking bugs will expose |
| 60 | +different facets of the same problem. |
| 61 | + |
| 62 | +## Bisecting regressions |
| 63 | + |
| 64 | +For regressions (something that used to work, but no longer does), it |
| 65 | +is super useful if we can figure out precisely when the code stopped |
| 66 | +working. The gold standard is to be able to identify the precise |
| 67 | +**PR** that broke the code, so we can ping the author, but even |
| 68 | +narrowing it down to a nightly build is helpful, especially as that |
| 69 | +then gives us a range of PRs. (One other challenge is that we |
| 70 | +sometimes land "rollup" PRs, which combine multiple PRs into one.) |
| 71 | + |
| 72 | +### cargo-bisect-rustc |
| 73 | + |
| 74 | +To help in figuring out the cause of a regression we have a tool |
| 75 | +called [cargo-bisect-rustc]. It will automatically download and test |
| 76 | +various builds of rustc. For recent regressions, it is even able to |
| 77 | +use the builds from our CI to track down the regression to a specific |
| 78 | +PR; for older regressions, it will simply identify a nightly. |
| 79 | + |
| 80 | +To learn to use [cargo-bisect-rustc], check out [this blog |
| 81 | +post][learn], which gives a quick introduction to how it works. You |
| 82 | +can also ask questions at the Zulip stream |
| 83 | +[`#t-compiler/cargo-bisect-rustc`][zcbr], or help in improving the tool. |
| 84 | + |
| 85 | +[cargo-bisect-rustc]: https://github.com/rust-lang/cargo-bisect-rustc/ |
| 86 | +[learn]: https://blog.rust-lang.org/inside-rust/2019/12/18/bisecting-rust-compiler.html |
| 87 | +[zcbr]: https://rust-lang.zulipchat.com/#narrow/stream/217417-t-compiler.2Fcargo-bisect-rustc |
| 88 | + |
| 89 | +### identifying the range of PRs in a nightly |
| 90 | + |
| 91 | +If the regression occurred more than 90 days ago, then |
| 92 | +cargo-bisect-rustc will not able to identify the particular PR that |
| 93 | +caused the regression, just the nightly build. In that case, we can |
| 94 | +identify the set of PRs that this corresponds to by using the git |
| 95 | +history. |
| 96 | + |
| 97 | +The command `rustc +nightly -vV` will cause rustc to output a number |
| 98 | +of useful bits of version info, including the `commit-hash`. Given the |
| 99 | +commit-hash of two nightly versions, you can find all of PRs that have |
| 100 | +landed in between by taking the following steps: |
| 101 | + |
| 102 | +1. Go to an update checkout of the [rust-lang/rust] repository |
| 103 | +2. Execute the command `git log --author=bors --format=oneline SHA1..SHA2` |
| 104 | + * This will list out all of the commits by bors, which is our merge bot |
| 105 | + * Each commit corresponds to one PR, and information about the PR should be in the description |
| 106 | +3. Copy and paste that information into the bug report |
| 107 | + |
| 108 | +Often, just eye-balling the PR descriptions (which are included in the |
| 109 | +commit messages) will give you a good idea which one likely caused the |
| 110 | +problem. But if you're unsure feel free to just ping the compiler team |
| 111 | +(`@rust-lang/compiler`) or else to ping the authors of the PR |
| 112 | +themselves. |
| 113 | + |
| 114 | +[rust-lang/rust]: https://github.com/rust-lang/rust/ |
0 commit comments