add a bit about crater

Author: mark-i-m

src/tests/intro.md

@@ -170,7 +170,38 @@ communicate with the server to coordinate running tests (see
 
 ## Crater
 
-TODO
+[Crater](https://github.com/rust-lang-nursery/crater) is a tool for compiling
+and running tests for _every_ crate on [crates.io](https://crates.io/). It is
+mainly used for checking for extent of breakage when implementing potentially
+breaking changes.
+
+### When to run Crater
+
+You should request a crater run if your PR makes large changes to the compiler
+or could cause breakage. If you are unsure, feel free to ask your PR's reviewer.
+
+### Requesting Crater Runs
+
+The rust team maintains a few machines that can be used for running crater runs
+on the changes introduced by a PR. If your PR needs a crater run, leave a
+comment for the triage team in the PR thread. Your will be enqueued by the
+triage team and the results will be posted when they are ready. A crater run
+usually takes a few days (as of this writing).
+
+While crater is really useful, it is also important to be aware of a few caveats:
+
+- Not all code is on crates.io! There is a lot of code in repos on GitHub and
+  elsewhere. Also, companies may not wish to publish their code. Thus, a
+  successful crater run is not a magically green light that there will be no
+  breakage; you still need to be careful.
+
+- Crater only runs Linux builds (on x86_64, I believe). Thus, other
+  architectures and platforms are not tested. Critically, this includes
+  Windows.
+
+- Many crates are not tested. This could be for a lot of reasons, including
+  that the crate doesn't compile any more (e.g. used old nightly features),
+  has broken or flaky tests, requires network access, or other reasons.
 
 ## Further reading