src/doc/rustc-dev-guide/src/ice-breaker/cleanup-crew.md

   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/