write about processes

1 files changed, 102 insertions, 6 deletions

diff --git a/src/doc/rustc-dev-guide/src/getting-started.md b/src/doc/rustc-dev-guide/src/getting-started.md
index bc8d6648a72..1ec7b1b2654 100644
--- a/src/doc/rustc-dev-guide/src/getting-started.md
+++ b/src/doc/rustc-dev-guide/src/getting-started.md
@@ -199,25 +199,121 @@ TODO: talk about things like miri, clippy, chalk, etc
 There are some official procedures to know about. This is a tour of the
 highlights, but there are a lot more details, which we will link to below.
 
-### Bug Fixes
+### Code Review
 
-TODO: talk about bors, highfive
+When you open a PR on the `rust-lang/rust` repo, a bot called `@highfive` will
+automatically assign a reviewer to the PR. The reviewer is the person that will
+approve the PR to be tested and merged. If you want a specific reviewer (e.g. a
+team member you've been working with), you can specifically request them by
+writing `r? @user` (e.g. `r? @eddyb`) in either the original post or a followup
+comment.
+
+The reviewer may request some changes using the GitHub code review interface.
+They may also request special procedures (such as a crater run; see below) for
+some PRs.
+
+When the PR is ready to be merged, the reviewer will issue a command to
+`@bors`, the CI bot. Usually, this is `@bors r+` or `@bors r=@user` to approve
+a PR (there are few other commands, but they are less relevant here). This puts
+the PR in [bors's queue][bors] to be tested and merged. Be patient; this can take a
+while and the queue can sometimes be long. PRs are never merged by hand.
+
+[bors]: https://buildbot2.rust-lang.org/homu/queue/rust
+
+### Bug Fixes or "Normal" code changes
+
+For most PRs, no special procedures are needed. You can just open a PR, and it
+will be reviewed, approved, and merged. This includes most bug fixes,
+refactorings, and other user-invisible changes. The next few sections talk
+about exceptions to this rule.
 
 ### New Features
 
-TODO: talk about RFCs, stabilization
+Rust has strong backwards-compatibility guarantees. Thus, new features can't
+just be implemented directly in stable Rust. Instead, we have 3 release
+channels: stable, beta, and nightly.
+
+- **Stable**: this is the latest stable release for general usage.
+- **Beta**: this is the next release (will be stable within 6 weeks).
+- **Nightly**: follows the `master` branch of the repo. This is the only
+  channel where unstable, incomplete, or experimental features are usable with
+  feature gates.
+
+In order to implement a new feature, usually you will need to go through [the
+RFC process][rfc] to propose a design, have discussions, etc. In some cases,
+small features can be added with only an FCP (see below). If in doubt, ask the
+compiler, language, or libs team (whichever is most relevant).
+
+[rfc]: https://github.com/rust-lang/rfcs/blob/master/README.md
+
+After a feature is approved to be added, a tracking issue is created on the
+`rust-lang/rust` repo, which tracks the progress towards the implementation of
+the feature, any bugs reported, and eventually stabilization.
+
+The feature then needs to be implemented behind a feature gate, which prevents
+it from being accidentally used.
+
+Finally, somebody may propose stabilizing the feature in an upcoming version of
+Rust. This requires an FCP (see below) to get the approval of the relevant teams.
+
+After that, the feature gate can be removed and the feature turned on for all users.
+
+[For more details on this process, see this chapter.](./implementing_new_features.md)
 
 ### Breaking Changes
 
-TODO: talk about crater, FCP, etc
+As mentioned above, Rust has strong backwards-compatibility guarantees. To this
+end, we are reluctant to make breaking changes. However, sometimes they are
+needed to correct compiler bugs (e.g. code that compiled but should not).
+
+Depending on the scale of the breakage, there are a few different actions that
+can be taken.  If the reviewer believes the breakage is very minimal (i.e. very
+unlikely to be actually encountered by users), they may just merge the change.
+More often, they will request a Final Comment Period (FCP), which calls for
+rough consensus among the members of a relevant team. The team members can
+discuss the issue and either accept, reject, or request changes on the PR.
+
+If the scale of breakage is large, a deprecation warning may be needed. This is
+a warning that the compiler will display to users whose code will break in the
+future.  After some time, an FCP can be used to move forward with the actual
+breakage.
+
+If the scale of breakage is unknown, a team member or contributor may request a
+[crater] run. This 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]: https://github.com/rust-lang/crater
 
 ### Major Changes
 
-TODO: talk about MCP
+The compiler team has a special process for large changes, whether or not they
+cause breakage. This process is call Major Change Proposal (MCP). MCP is a
+relatively lightweight mechanism for getting feedback on large changes to the
+compiler (as opposed to a full RFC or a design meeting with the team).
+
+Example of things that might require MCPs include major refactorings, changes
+to important types, or important changes to how the compiler does something.
+
+**When in doubt, ask on [zulip][z]. We would hate for you to put a lot of work
+into a PR that ends up not getting merged!**
 
 ### Performance
 
-TODO: Talk about perf runs
+Compiler performance is important. We have put a lot of effort over the last
+few years into [gradually improving it][perfdash].
+
+[perfdash]: https://perf.rust-lang.org/dashboard.html
+
+If you suspect that your change may cause a performance regression (or
+improvement), you can request a "perf run" (your reviewer may also request one
+before approving). This is yet another bot that will compile a collection of
+benchmarks on a compiler with your changes. The numbers are reported
+[here][perf], and you can see a comparison of your changes against the latest
+master.
+
+[perf]: https://perf.rust-lang.org/dashboard.html
 
 ## Other Resources