diff --git a/src/getting-started.md b/src/getting-started.md index bc8d6648..1ec7b1b2 100644 --- a/src/getting-started.md +++ b/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