create guide to ICE-breaker groups and specifically advice for LLVM (#452)

Author: nikomatsakis

src/SUMMARY.md

@@ -23,6 +23,8 @@
     - [Coding conventions](./conventions.md)
     - [crates.io Dependencies](./crates-io.md)
     - [Emitting Errors and other Diagnostics](diagnostics.md)
+    - [ICE-breaker teams](ice-breaker/about.md)
+        - [LLVM ICE-breakers](ice-breaker/llvm.md)
 - [Part 2: How rustc works](./part-2-intro.md)
     - [High-level overview of the compiler source](./high-level-overview.md)
     - [The Rustc Driver and Interface](./rustc-driver.md)

src/codegen/debugging.md

@@ -94,6 +94,36 @@ $ ./build/$TRIPLE/llvm/bin/llvm-extract \
     > extracted.ll
 ```
 
+### Getting help and asking questions
+
+If you have some questions, head over to the [rust-lang Zulip] and
+specifically the `#t-compiler/wg-llvm` stream.
+
+[rust-lang Zulip]: https://rust-lang.zulipchat.com/
+
+### Compiler options to know and love
+
+The `-Chelp` and `-Zhelp` compiler switches will list out a variety
+of interesting options you may find useful. Here are a few of the most
+common that pertain to LLVM development (some of them are employed in the
+tutorial above):
+
+- The `--emit llvm-ir` option emits a `<filename>.ll` file with LLVM IR in textual format
+    - The `--emit llvm-bc` option emits in bytecode format (`<filename>.bc`)
+- Passing `-Cllvm-arg=<foo>` allows passing pretty much all the
+  options that tools like llc and opt would accept;
+  e.g. `-Cllvm-arg=-print-before-all` to print IR before every LLVM
+  pass.
+- The `-Cno-prepopulate-passes` will avoid pre-populate the LLVM pass
+  manager with a list of passes.  This will allow you to view the LLVM
+  IR that rustc generates, not the LLVM IR after optimizations.
+- The `-Cpasses=val` option allows you to supply a (space seprated) list of extra LLVM passes to run
+- The `-Csave-temps` option saves all temporary output files during compilation
+- The `-Zprint-llvm-passes` option will print out LLVM optimization passes being run
+- The `-Ztime-llvm-passes` option measures the time of each LLVM pass
+- The `-Zverify-llvm-ir` option will verify the LLVM IR for correctness
+- The `-Zno-parallel-llvm` will disable parallel compilation of distinct compilation units
+
 ### Filing LLVM bug reports
 
 When filing an LLVM bug report, you will probably want some sort of minimal
@@ -119,4 +149,18 @@ create a minimal working example with Godbolt. Go to
    optimizations transform it.
 
 5. Once you have a godbolt link demonstrating the issue, it is pretty easy to
-   fill in an LLVM bug.
+   fill in an LLVM bug. Just visit [bugs.llvm.org](https://bugs.llvm.org/).
+
+### Porting bug fixes from LLVM
+
+Once you've identified the bug as an LLVM bug, you will sometimes
+find that it has already been reported and fixed in LLVM, but we haven't
+gotten the fix yet (or perhaps you are familiar enough with LLVM to fix it yourself).
+
+In that case, we can sometimes opt to port the fix for the bug
+directly to our own LLVM fork, so that rustc can use it more easily.
+Our fork of LLVM is maintained in [rust-lang/llvm-project]. Once
+you've landed the fix there, you'll also need to land a PR modifying
+our submodule commits -- ask around on Zulip for help.
+
+[rust-lang/llvm-project]: https://github.com/rust-lang/llvm-project/

src/ice-breaker/about.md

@@ -0,0 +1,37 @@
+# ICE-breakers
+
+The **ICE-breaker groups** are an easy way to help out with rustc in a
+"piece-meal" fashion, without committing to a larger project.
+ICE-breaker groups are **[easy to join](#join)** (just submit a PR!)
+and joining does not entail any particular commitment.
+
+Once you [join an ICE ICE-breaker group](#join), you will be added to
+a list that receives pings on github whenever a new issue is found
+that fits the ICE-breaker group's criteria. If you are interested, you
+can then [claim the issue] and start working on it.
+
+Of course, you don't have to wait for new issues to be tagged! If you
+prefer, you can use the Github label for an ICE-breaker group to
+search for existing issues that haven't been claimed yet.
+
+## What issues are a good fit for ICE-breaker groups?
+
+"ICE-breaker issues" are intended to be **isolated** bugs of **middle
+priority**:
+
+- By **isolated**, we mean that we do not expect large-scale refactoring
+  to be required to fix the bug.
+- By **middle priority**, we mean that we'd like to see the bug fixed,
+  but it's not such a burning problem that we are dropping everything
+  else to fix it. The danger with such bugs, of course, is that they
+  can accumulate over time, and the role of the ICE-breaker groups is
+  to try and stop that from happening!
+
+<a name="join"></a>
+
+## Joining an ICE-breaker group
+
+TBD -- we are building this mechanism right now! In the meantime, drop
+in on Zulip and leave your github name in [this topic][topic].
+
+[topic]: https://rust-lang.zulipchat.com/#narrow/stream/187780-t-compiler.2Fwg-llvm/topic/llvm.20ice-breaker.20registration

src/ice-breaker/llvm.md

@@ -0,0 +1,31 @@
+# LLVM ICE-breakers
+
+**Github Label:** [ICEBreaker-LLVM]
+
+[ICEBreaker-LLVM]: https://github.com/rust-lang/rust/labels/ICEBreaker-LLVM
+
+The "LLVM ICE-breakers" are focused on bugs that center around LLVM.
+These bugs often arise because of LLVM optimizations gone awry, or as
+the result of an LLVM upgrade. The goal here is:
+
+- to determine whether the bug is a result of us generating invalid LLVM IR,
+  or LLVM misoptimizing;
+- if the former, to fix our IR;
+- if the latter, to try and file a bug on LLVM (or identify an existing bug).
+
+## Helpful tips and options
+
+The ["Debugging LLVM"][d] section of the
+rustc-guide gives a step-by-step process for how to help debug bugs
+caused by LLVM. In particular, it discusses how to emit LLVM IR, run
+the LLVM IR optimization pipeliness, and so forth. You may also find
+it useful to look at the various codegen options listed under `-Chelp`
+and the internal options under `-Zhelp` -- there are a number that
+pertain to LLVM (just search for LLVM).
+
+[d]: ../codegen/debugging.md
+
+## If you do narrow to an LLVM bug
+
+The ["Debugging LLVM"][d] section also describes what to do once
+you've identified the bug.