Rearrange the "getting started" and contributing.md sections

There was a lot of information duplicated between the two, and it wasn't
clear which one to look. This commit changes `contributing.md` to be
strictly for contribution procedures, and moves "what should I work on"
sections to "Getting Started".

This also consolidates the links in `about-this-guide.md` rather than
spreading them between about-this-guide, getting-started, and
contributing.

I suggest using https://rustc-dev-guide.org/git.html#moving-large-sections-of-code to review this commit.

src/SUMMARY.md

@@ -35,7 +35,7 @@
 
 # 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)

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/contributing.md

@@ -1,31 +1,4 @@
-# Contributing to Rust
-
-Thank you for your interest in contributing to Rust! There are many ways to
-contribute, and we appreciate all of them.
-
-<!-- toc -->
-
-If you have questions, please make a post on [internals.rust-lang.org][internals] or
-hop on the [Rust Discord server][rust-discord] or [Rust Zulip server][rust-zulip].
-
-As a reminder, all contributors are expected to follow our [Code of Conduct][coc].
-
-If this is your first time contributing, the [Getting Started] and
-[walkthrough] chapters can give you a good example of how a typical
-contribution would go.
-
-[internals]: https://internals.rust-lang.org
-[rust-discord]: http://discord.gg/rust-lang
-[rust-zulip]: https://rust-lang.zulipchat.com
-[coc]: https://www.rust-lang.org/conduct.html
-[walkthrough]: ./walkthrough.md
-[Getting Started]: ./getting-started.md
-
-## Feature Requests
-
-Feature requests need to go through a process to be approved by the relevant
-teams. Usually this requires a Final Comment Period (FCP) or even a Request for
-Comments (RFC). See [Getting Started] for more information about these processes.
+# Contribution Procedures
 
 ## Bug Reports
 
@@ -58,6 +31,121 @@ Opening an issue is as easy as following [this
 link](https://github.com/rust-lang/rust/issues/new/choose) and filling out the fields
 in the appropriate provided template.
 
+## Bug Fixes or "Normal" code changes
+
+For most PRs, no special procedures are needed. You can just [open a PR][prs], 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.
+
+Also, note that it is perfectly acceptable to open WIP PRs or GitHub [Draft
+PRs][draft]. Some people prefer to do this so they can get feedback along the
+way or share their code with a collaborator. Others do this so they can utilize
+the CI to build and test their PR (e.g. if you are developing on a laptop).
+
+[prs]: #pull-requests
+[draft]: https://github.blog/2019-02-14-introducing-draft-pull-requests/
+
+## New Features
+
+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][break]). 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 a Final Comment Period ([see below][break]) 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 on implementing new
+features.](./implementing_new_features.md)
+
+### Breaking Changes
+
+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) or
+make progress on some features.
+
+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
+
+The compiler team has a special process for large changes, whether or not they
+cause breakage. This process is called a 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, or
+smaller user-facing changes.
+
+**When in doubt, ask on [zulip][z]. It would be a shame to put a lot of work
+into a PR that ends up not getting merged!** [See this document][mcpinfo] for
+more info on MCPs.
+
+[mcpinfo]: https://forge.rust-lang.org/compiler/mcp.html
+[z]: https://rust-lang.zulipchat.com/#narrow/stream/131828-t-compiler
+
+### Performance
+
+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.
+
+For an introduction to the performance of Rust code in general
+which would also be useful in rustc development, see [The Rust Performance Book].
+
+[perf]: https://perf.rust-lang.org
+[The Rust Performance Book]: https://nnethercote.github.io/perf-book/
+
 ## Pull Requests
 
 Pull requests (or PRs for short) are the primary mechanism we use to change Rust.
@@ -96,6 +184,8 @@ For a full list of possible `groupname` check the `adhoc_groups` section at the
 or the list of teams in the [rust-lang teams
 database](https://github.com/rust-lang/team/tree/master/teams).
 
+### Waiting for reviews
+
 > NOTE
 >
 > Pull request reviewers are often working at capacity,
@@ -113,6 +203,23 @@ database](https://github.com/rust-lang/team/tree/master/teams).
 >   the author is ready for a review,
 >   and this PR will be queued again in the reviewer's queue.
 
+Please note that the reviewers are humans, who for the most part work on `rustc`
+in their free time. This means that they can take some time to respond and review
+your PR. It also means that reviewers can miss some PRs that are assigned to them.
+
+To try to move PRs forward, the Triage WG regularly goes through all PRs that
+are waiting for review and haven't been discussed for at least 2 weeks. If you
+don't get a review within 2 weeks, feel free to ask the Triage WG on
+Zulip ([#t-release/triage]). They have knowledge of when to ping, who might be
+on vacation, etc.
+
+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][break]) for some PRs.
+
+[r?]: https://github.com/rust-lang/rust/pull/78133#issuecomment-712692371
+[#t-release/triage]: https://rust-lang.zulipchat.com/#narrow/stream/242269-t-release.2Ftriage
+[break]: #breaking-changes
 ### CI
 
 In addition to being reviewed by a human, pull requests are automatically tested
@@ -152,6 +259,8 @@ Changes that are rolled up are tested and merged alongside other PRs, to
 speed the process up. Typically only small changes that are expected not to conflict
 with one another are marked as "always roll up".
 
+Be patient; this can take a while and the queue can sometimes be long. PRs are never merged by hand.
+
 [@rustbot]: https://github.com/rustbot
 [@bors]: https://github.com/bors
 [merge-queue]: https://bors.rust-lang.org/queue/rust
@@ -198,7 +307,7 @@ the issue in question.
 
 ## External Dependencies
 
-This sections has moved to ["Using External Repositories"](./external-repos.md).
+This section has moved to ["Using External Repositories"](./external-repos.md).
 
 ## Writing Documentation
 
@@ -400,64 +509,8 @@ This is used for [RFCs], issues, and pull requests.
 [rfcbot]: https://github.com/anp/rfcbot-rs/
 [RFCs]: https://github.com/rust-lang/rfcs
 
-## Out-of-tree Contributions
-
-There are a number of other ways to contribute to Rust that don't deal with
-rust-lang/rust:
-
-* Answer questions in the _Get Help!_ channels on the [Rust Discord
-  server][rust-discord], on [users.rust-lang.org][users], or on
-  [StackOverflow][so].
-* Participate in the [RFC process](https://github.com/rust-lang/rfcs).
-* Find a [requested community library][community-library], build it, and publish
-  it to [Crates.io](http://crates.io). Easier said than done, but very, very
-  valuable!
-
-[rust-discord]: https://discord.gg/rust-lang
-[users]: https://users.rust-lang.org/
-[so]: http://stackoverflow.com/questions/tagged/rust
-[community-library]: https://github.com/rust-lang/rfcs/labels/A-community-library
-
 ## Helpful Links and Information
 
-For people new to Rust, and just starting to contribute, or even for
-more seasoned developers, some useful places to look for information
-are:
-
-* This guide contains information about how various parts of the
-  compiler work and how to contribute to the compiler
-* [Rust Forge][rustforge] contains additional documentation, including
-  write-ups of how to achieve common tasks
-* The [Rust Internals forum][rif], a place to ask questions and
-  discuss Rust's internals
-* The [generated documentation for Rust's compiler][gdfrustc]
-* 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!
-* Don't be afraid to ask! The Rust community is friendly and helpful.
-
-[rustc dev guide]: about-this-guide.md
-[gdfrustc]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/
-[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
+This section has moved to the ["About this guide"][more-links] chapter.
+
+[more-links]: ./about-this-guide.md#other-places-to-find-information