Consolidate, deduplicate, and link information for getting started

src/SUMMARY.md

@@ -35,17 +35,18 @@
 
 # Contributing to Rust
 
-- [Introduction](./contributing.md)
+- [Contribution Procedures](./contributing.md)
 - [About the compiler team](./compiler-team.md)
 - [Using Git](./git.md)
 - [Mastering @rustbot](./rustbot.md)
 - [Walkthrough: a typical contribution](./walkthrough.md)
-- [Bug Fix Procedure](./bug-fix-procedure.md)
+- [Procedures for Breaking Changes](./bug-fix-procedure.md)
 - [Implementing new features](./implementing_new_features.md)
 - [Stability attributes](./stability.md)
 - [Stabilizing Features](./stabilization_guide.md)
 - [Feature Gates](./feature-gates.md)
 - [Coding conventions](./conventions.md)
+- [Using external repositories](./external-repos.md)
 - [Fuzzing](./fuzzing.md)
 - [Notification groups](notification-groups/about.md)
     - [ARM](notification-groups/arm.md)

src/about-this-guide.md

@@ -58,14 +58,52 @@ please see the corresponding [subsection on writing documentation in this guide]
 
 You might also find the following sites useful:
 
+- This guide contains information about how various parts of the
+  compiler work and how to contribute to the compiler.
 - [rustc API docs] -- rustdoc documentation for the compiler
 - [Forge] -- contains documentation about Rust infrastructure, team procedures, and more
 - [compiler-team] -- the home-base for the Rust compiler team, with description
   of the team procedures, active working groups, and the team calendar.
 - [std-dev-guide] -- a similar guide for developing the standard library.
+- [The t-compiler zulip][z]
+- [The compiler's documentation (rustdocs)](https://doc.rust-lang.org/nightly/nightly-rustc/)
+- [The Forge](https://forge.rust-lang.org/) has more documentation about various procedures.
+- `#contribute` and `#wg-rustup` on [Discord](https://discord.gg/rust-lang).
+- The [Rust Internals forum][rif], a place to ask questions and
+  discuss Rust's internals
+- The [Rust reference][rr], even though it doesn't specifically talk about
+  Rust's internals, is a great resource nonetheless
+- Although out of date, [Tom Lee's great blog article][tlgba] is very helpful
+- [rustaceans.org][ro] is helpful, but mostly dedicated to IRC
+- The [Rust Compiler Testing Docs][rctd]
+- For [@bors], [this cheat sheet][cheatsheet] is helpful
+- Google is always helpful when programming.
+  You can [search all Rust documentation][gsearchdocs] (the standard library,
+  the compiler, the books, the references, and the guides) to quickly find
+  information about the language and compiler.
+- You can also use Rustdoc's built-in search feature to find documentation on
+  types and functions within the crates you're looking at. You can also search
+  by type signature! For example, searching for `* -> vec` should find all
+  functions that return a `Vec<T>`.
+  _Hint:_ Find more tips and keyboard shortcuts by typing `?` on any Rustdoc
+  page!
 
+
+[rustc dev guide]: about-this-guide.md
+[gsearchdocs]: https://www.google.com/search?q=site:doc.rust-lang.org+your+query+here
+[stddocs]: https://doc.rust-lang.org/std
+[rif]: http://internals.rust-lang.org
+[rr]: https://doc.rust-lang.org/book/README.html
+[rustforge]: https://forge.rust-lang.org/
+[tlgba]: https://tomlee.co/2014/04/a-more-detailed-tour-of-the-rust-compiler/
+[ro]: https://www.rustaceans.org/
+[rctd]: tests/intro.md
+[cheatsheet]: https://bors.rust-lang.org/
+[Miri]: https://github.com/rust-lang/miri
+[@bors]: https://github.com/bors
 [GitHub repository]: https://github.com/rust-lang/rustc-dev-guide/
 [rustc API docs]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/
 [Forge]: https://forge.rust-lang.org/
 [compiler-team]: https://github.com/rust-lang/compiler-team/
 [std-dev-guide]: https://std-dev-guide.rust-lang.org/
+[z]: https://rust-lang.zulipchat.com/#narrow/stream/131828-t-compiler

src/bug-fix-procedure.md

@@ -1,4 +1,4 @@
-# Rustc Bug Fix Procedure
+# Procedures for Breaking Changes
 
 <!-- toc -->
 
@@ -169,6 +169,13 @@ there were no errors before.
 
 #### Crater and crates.io
 
+[Crater] is a bot that will compile all crates.io crates and many
+public github repos with the compiler with your changes. A report will then be
+generated with crates that ceased to compile with or began to compile with your
+changes. Crater runs can take a few days to complete.
+
+[Crater]: ./tests/crater.md
+
 We should always do a crater run to assess impact. It is polite and considerate
 to at least notify the authors of affected crates the breaking change. If we can
 submit PRs to fix the problem, so much the better.

src/building/how-to-build-and-run.md

@@ -1,5 +1,7 @@
 # How to build and run the compiler
 
+<!-- toc -->
+
 The compiler is built using a tool called `x.py`. You will need to
 have Python installed to run it.
 
@@ -52,7 +54,34 @@ If you have already built `rustc` and you change settings related to LLVM, then
 execute `rm -rf build` for subsequent configuration changes to take effect. Note that `./x.py
 clean` will not cause a rebuild of LLVM.
 
-## Building the compiler
+## Common `x.py` commands
+
+Here are the basic invocations of the `x.py` commands most commonly used when
+working on `rustc`, `std`, `rustdoc`, and other tools.
+
+| Command | When to use it |
+| --- | --- |
+| `./x.py check` | Quick check to see if most things compile; [rust-analyzer can run this automatically for you][rust-analyzer] |
+| `./x.py build` | Builds `rustc`, `std`, and `rustdoc` |
+| `./x.py test` | Runs all tests |
+| `./x.py fmt` | Formats all code |
+
+As written, these commands are reasonable starting points. However, there are
+additional options and arguments for each of them that are worth learning for
+serious development work. In particular, `./x.py build` and `./x.py test`
+provide many ways to compile or test a subset of the code, which can save a lot
+of time.
+
+Also, note that `x.py` supports all kinds of path suffixes for `compiler`, `library`,
+and `src/tools` directories. So, you can simply run `x.py test tidy` instead of
+`x.py test src/tools/tidy`. Or, `x.py build std` instead of `x.py build library/std`.
+
+[rust-analyzer]: ./building/suggested.html#configuring-rust-analyzer-for-rustc
+
+See the chapters on [building](./building/how-to-build-and-run.md),
+[testing](./tests/intro.md), and [rustdoc](./rustdoc.md) for more details.
+
+### Building the compiler
 
 Note that building will require a relatively large amount of storage space.
 You may want to have upwards of 10 or 15 gigabytes available to build the compiler.
@@ -98,7 +127,7 @@ build. The **full** `rustc` build (what you get with `./x.py build
 
 You almost never need to do this.
 
-## Build specific components
+### Build specific components
 
 If you are working on the standard library, you probably don't need to build
 the compiler unless you are planning to use a recently added nightly feature.

src/building/new-target.md

@@ -4,6 +4,8 @@ These are a set of steps to add support for a new target. There are
 numerous end states and paths to get there, so not all sections may be
 relevant to your desired goal.
 
+<!-- toc -->
+
 ## Specifying a new LLVM
 
 For very new targets, you may need to use a different fork of LLVM

src/building/suggested.md

@@ -3,6 +3,8 @@
 The full bootstrapping process takes quite a while. Here are some suggestions
 to make your life easier.
 
+<!-- toc -->
+
 ## Installing a pre-push hook
 
 CI will automatically fail your build if it doesn't pass `tidy`, our