Skip to content

Commit 92102e0

Browse files
jyn514jyn514
committed
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.
1 parent cdd2e49 commit 92102e0

File tree

4 files changed

+216
-246
lines changed

4 files changed

+216
-246
lines changed

‎src/SUMMARY.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@
3535

3636
# Contributing to Rust
3737

38-
- [Introduction](./contributing.md)
38+
- [Contribution Procedures](./contributing.md)
3939
- [About the compiler team](./compiler-team.md)
4040
- [Using Git](./git.md)
4141
- [Mastering @rustbot](./rustbot.md)

‎src/about-this-guide.md

+38
Original file line numberDiff line numberDiff line change
@@ -58,14 +58,52 @@ please see the corresponding [subsection on writing documentation in this guide]
5858

5959
You might also find the following sites useful:
6060

61+
- This guide contains information about how various parts of the
62+
compiler work and how to contribute to the compiler.
6163
- [rustc API docs] -- rustdoc documentation for the compiler
6264
- [Forge] -- contains documentation about Rust infrastructure, team procedures, and more
6365
- [compiler-team] -- the home-base for the Rust compiler team, with description
6466
of the team procedures, active working groups, and the team calendar.
6567
- [std-dev-guide] -- a similar guide for developing the standard library.
68+
- [The t-compiler zulip][z]
69+
- [The compiler's documentation (rustdocs)](https://doc.rust-lang.org/nightly/nightly-rustc/)
70+
- [The Forge](https://forge.rust-lang.org/) has more documentation about various procedures.
71+
- `#contribute` and `#wg-rustup` on [Discord](https://discord.gg/rust-lang).
72+
- The [Rust Internals forum][rif], a place to ask questions and
73+
discuss Rust's internals
74+
- The [Rust reference][rr], even though it doesn't specifically talk about
75+
Rust's internals, is a great resource nonetheless
76+
- Although out of date, [Tom Lee's great blog article][tlgba] is very helpful
77+
- [rustaceans.org][ro] is helpful, but mostly dedicated to IRC
78+
- The [Rust Compiler Testing Docs][rctd]
79+
- For [@bors], [this cheat sheet][cheatsheet] is helpful
80+
- Google is always helpful when programming.
81+
You can [search all Rust documentation][gsearchdocs] (the standard library,
82+
the compiler, the books, the references, and the guides) to quickly find
83+
information about the language and compiler.
84+
- You can also use Rustdoc's built-in search feature to find documentation on
85+
types and functions within the crates you're looking at. You can also search
86+
by type signature! For example, searching for `* -> vec` should find all
87+
functions that return a `Vec<T>`.
88+
_Hint:_ Find more tips and keyboard shortcuts by typing `?` on any Rustdoc
89+
page!
6690

91+
92+
[rustc dev guide]: about-this-guide.md
93+
[gsearchdocs]: https://www.google.com/search?q=site:doc.rust-lang.org+your+query+here
94+
[stddocs]: https://doc.rust-lang.org/std
95+
[rif]: http://internals.rust-lang.org
96+
[rr]: https://doc.rust-lang.org/book/README.html
97+
[rustforge]: https://forge.rust-lang.org/
98+
[tlgba]: https://tomlee.co/2014/04/a-more-detailed-tour-of-the-rust-compiler/
99+
[ro]: https://www.rustaceans.org/
100+
[rctd]: tests/intro.md
101+
[cheatsheet]: https://bors.rust-lang.org/
102+
[Miri]: https://github.com/rust-lang/miri
103+
[@bors]: https://github.com/bors
67104
[GitHub repository]: https://github.com/rust-lang/rustc-dev-guide/
68105
[rustc API docs]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/
69106
[Forge]: https://forge.rust-lang.org/
70107
[compiler-team]: https://github.com/rust-lang/compiler-team/
71108
[std-dev-guide]: https://std-dev-guide.rust-lang.org/
109+
[z]: https://rust-lang.zulipchat.com/#narrow/stream/131828-t-compiler

‎src/contributing.md

+141-88
Original file line numberDiff line numberDiff line change
@@ -1,31 +1,4 @@
1-
# Contributing to Rust
2-
3-
Thank you for your interest in contributing to Rust! There are many ways to
4-
contribute, and we appreciate all of them.
5-
6-
<!-- toc -->
7-
8-
If you have questions, please make a post on [internals.rust-lang.org][internals] or
9-
hop on the [Rust Discord server][rust-discord] or [Rust Zulip server][rust-zulip].
10-
11-
As a reminder, all contributors are expected to follow our [Code of Conduct][coc].
12-
13-
If this is your first time contributing, the [Getting Started] and
14-
[walkthrough] chapters can give you a good example of how a typical
15-
contribution would go.
16-
17-
[internals]: https://internals.rust-lang.org
18-
[rust-discord]: http://discord.gg/rust-lang
19-
[rust-zulip]: https://rust-lang.zulipchat.com
20-
[coc]: https://www.rust-lang.org/conduct.html
21-
[walkthrough]: ./walkthrough.md
22-
[Getting Started]: ./getting-started.md
23-
24-
## Feature Requests
25-
26-
Feature requests need to go through a process to be approved by the relevant
27-
teams. Usually this requires a Final Comment Period (FCP) or even a Request for
28-
Comments (RFC). See [Getting Started] for more information about these processes.
1+
# Contribution Procedures
292

303
## Bug Reports
314

@@ -58,6 +31,121 @@ Opening an issue is as easy as following [this
5831
link](https://github.com/rust-lang/rust/issues/new/choose) and filling out the fields
5932
in the appropriate provided template.
6033

34+
## Bug Fixes or "Normal" code changes
35+
36+
For most PRs, no special procedures are needed. You can just [open a PR][prs], and it
37+
will be reviewed, approved, and merged. This includes most bug fixes,
38+
refactorings, and other user-invisible changes. The next few sections talk
39+
about exceptions to this rule.
40+
41+
Also, note that it is perfectly acceptable to open WIP PRs or GitHub [Draft
42+
PRs][draft]. Some people prefer to do this so they can get feedback along the
43+
way or share their code with a collaborator. Others do this so they can utilize
44+
the CI to build and test their PR (e.g. if you are developing on a laptop).
45+
46+
[prs]: #pull-requests
47+
[draft]: https://github.blog/2019-02-14-introducing-draft-pull-requests/
48+
49+
## New Features
50+
51+
Rust has strong backwards-compatibility guarantees. Thus, new features can't
52+
just be implemented directly in stable Rust. Instead, we have 3 release
53+
channels: stable, beta, and nightly.
54+
55+
- **Stable**: this is the latest stable release for general usage.
56+
- **Beta**: this is the next release (will be stable within 6 weeks).
57+
- **Nightly**: follows the `master` branch of the repo. This is the only
58+
channel where unstable, incomplete, or experimental features are usable with
59+
feature gates.
60+
61+
In order to implement a new feature, usually you will need to go through [the
62+
RFC process][rfc] to propose a design, have discussions, etc. In some cases,
63+
small features can be added with only an FCP ([see below][break]). If in doubt, ask the
64+
compiler, language, or libs team (whichever is most relevant).
65+
66+
[rfc]: https://github.com/rust-lang/rfcs/blob/master/README.md
67+
68+
After a feature is approved to be added, a tracking issue is created on the
69+
`rust-lang/rust` repo, which tracks the progress towards the implementation of
70+
the feature, any bugs reported, and eventually stabilization.
71+
72+
The feature then needs to be implemented behind a feature gate, which prevents
73+
it from being accidentally used.
74+
75+
Finally, somebody may propose stabilizing the feature in an upcoming version of
76+
Rust. This requires a Final Comment Period ([see below][break]) to get the
77+
approval of the relevant teams.
78+
79+
After that, the feature gate can be removed and the feature turned on for all users.
80+
81+
For more details on this process, see [this chapter on implementing new
82+
features.](./implementing_new_features.md)
83+
84+
### Breaking Changes
85+
86+
As mentioned above, Rust has strong backwards-compatibility guarantees. To this
87+
end, we are reluctant to make breaking changes. However, sometimes they are
88+
needed to correct compiler bugs (e.g. code that compiled but should not) or
89+
make progress on some features.
90+
91+
Depending on the scale of the breakage, there are a few different actions that
92+
can be taken. If the reviewer believes the breakage is very minimal (i.e. very
93+
unlikely to be actually encountered by users), they may just merge the change.
94+
More often, they will request a Final Comment Period (FCP), which calls for
95+
rough consensus among the members of a relevant team. The team members can
96+
discuss the issue and either accept, reject, or request changes on the PR.
97+
98+
If the scale of breakage is large, a deprecation warning may be needed. This is
99+
a warning that the compiler will display to users whose code will break in the
100+
future. After some time, an FCP can be used to move forward with the actual
101+
breakage.
102+
103+
If the scale of breakage is unknown, a team member or contributor may request a
104+
[crater] run. This is a bot that will compile all crates.io crates and many
105+
public github repos with the compiler with your changes. A report will then be
106+
generated with crates that ceased to compile with or began to compile with your
107+
changes. Crater runs can take a few days to complete.
108+
109+
[crater]: https://github.com/rust-lang/crater
110+
111+
### Major Changes
112+
113+
The compiler team has a special process for large changes, whether or not they
114+
cause breakage. This process is called a Major Change Proposal (MCP). MCP is a
115+
relatively lightweight mechanism for getting feedback on large changes to the
116+
compiler (as opposed to a full RFC or a design meeting with the team).
117+
118+
Example of things that might require MCPs include major refactorings, changes
119+
to important types, or important changes to how the compiler does something, or
120+
smaller user-facing changes.
121+
122+
**When in doubt, ask on [zulip][z]. It would be a shame to put a lot of work
123+
into a PR that ends up not getting merged!** [See this document][mcpinfo] for
124+
more info on MCPs.
125+
126+
[mcpinfo]: https://forge.rust-lang.org/compiler/mcp.html
127+
[z]: https://rust-lang.zulipchat.com/#narrow/stream/131828-t-compiler
128+
129+
### Performance
130+
131+
Compiler performance is important. We have put a lot of effort over the last
132+
few years into [gradually improving it][perfdash].
133+
134+
[perfdash]: https://perf.rust-lang.org/dashboard.html
135+
136+
If you suspect that your change may cause a performance regression (or
137+
improvement), you can request a "perf run" (your reviewer may also request one
138+
before approving). This is yet another bot that will compile a collection of
139+
benchmarks on a compiler with your changes. The numbers are reported
140+
[here][perf], and you can see a comparison of your changes against the latest
141+
master.
142+
143+
For an introduction to the performance of Rust code in general
144+
which would also be useful in rustc development, see [The Rust Performance Book].
145+
146+
[perf]: https://perf.rust-lang.org
147+
[The Rust Performance Book]: https://nnethercote.github.io/perf-book/
148+
61149
## Pull Requests
62150

63151
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
96184
or the list of teams in the [rust-lang teams
97185
database](https://github.com/rust-lang/team/tree/master/teams).
98186

187+
### Waiting for reviews
188+
99189
> NOTE
100190
>
101191
> Pull request reviewers are often working at capacity,
@@ -113,6 +203,23 @@ database](https://github.com/rust-lang/team/tree/master/teams).
113203
> the author is ready for a review,
114204
> and this PR will be queued again in the reviewer's queue.
115205
206+
Please note that the reviewers are humans, who for the most part work on `rustc`
207+
in their free time. This means that they can take some time to respond and review
208+
your PR. It also means that reviewers can miss some PRs that are assigned to them.
209+
210+
To try to move PRs forward, the Triage WG regularly goes through all PRs that
211+
are waiting for review and haven't been discussed for at least 2 weeks. If you
212+
don't get a review within 2 weeks, feel free to ask the Triage WG on
213+
Zulip ([#t-release/triage]). They have knowledge of when to ping, who might be
214+
on vacation, etc.
215+
216+
The reviewer may request some changes using the GitHub code review interface.
217+
They may also request special procedures (such as a [crater] run; [see
218+
below][break]) for some PRs.
219+
220+
[r?]: https://github.com/rust-lang/rust/pull/78133#issuecomment-712692371
221+
[#t-release/triage]: https://rust-lang.zulipchat.com/#narrow/stream/242269-t-release.2Ftriage
222+
[break]: #breaking-changes
116223
### CI
117224

118225
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
152259
speed the process up. Typically only small changes that are expected not to conflict
153260
with one another are marked as "always roll up".
154261

262+
Be patient; this can take a while and the queue can sometimes be long. PRs are never merged by hand.
263+
155264
[@rustbot]: https://github.com/rustbot
156265
[@bors]: https://github.com/bors
157266
[merge-queue]: https://bors.rust-lang.org/queue/rust
@@ -198,7 +307,7 @@ the issue in question.
198307

199308
## External Dependencies
200309

201-
This sections has moved to ["Using External Repositories"](./external-repos.md).
310+
This section has moved to ["Using External Repositories"](./external-repos.md).
202311

203312
## Writing Documentation
204313

@@ -400,64 +509,8 @@ This is used for [RFCs], issues, and pull requests.
400509
[rfcbot]: https://github.com/anp/rfcbot-rs/
401510
[RFCs]: https://github.com/rust-lang/rfcs
402511

403-
## Out-of-tree Contributions
404-
405-
There are a number of other ways to contribute to Rust that don't deal with
406-
rust-lang/rust:
407-
408-
* Answer questions in the _Get Help!_ channels on the [Rust Discord
409-
server][rust-discord], on [users.rust-lang.org][users], or on
410-
[StackOverflow][so].
411-
* Participate in the [RFC process](https://github.com/rust-lang/rfcs).
412-
* Find a [requested community library][community-library], build it, and publish
413-
it to [Crates.io](http://crates.io). Easier said than done, but very, very
414-
valuable!
415-
416-
[rust-discord]: https://discord.gg/rust-lang
417-
[users]: https://users.rust-lang.org/
418-
[so]: http://stackoverflow.com/questions/tagged/rust
419-
[community-library]: https://github.com/rust-lang/rfcs/labels/A-community-library
420-
421512
## Helpful Links and Information
422513

423-
For people new to Rust, and just starting to contribute, or even for
424-
more seasoned developers, some useful places to look for information
425-
are:
426-
427-
* This guide contains information about how various parts of the
428-
compiler work and how to contribute to the compiler
429-
* [Rust Forge][rustforge] contains additional documentation, including
430-
write-ups of how to achieve common tasks
431-
* The [Rust Internals forum][rif], a place to ask questions and
432-
discuss Rust's internals
433-
* The [generated documentation for Rust's compiler][gdfrustc]
434-
* The [Rust reference][rr], even though it doesn't specifically talk about
435-
Rust's internals, is a great resource nonetheless
436-
* Although out of date, [Tom Lee's great blog article][tlgba] is very helpful
437-
* [rustaceans.org][ro] is helpful, but mostly dedicated to IRC
438-
* The [Rust Compiler Testing Docs][rctd]
439-
* For [@bors], [this cheat sheet][cheatsheet] is helpful
440-
* Google is always helpful when programming.
441-
You can [search all Rust documentation][gsearchdocs] (the standard library,
442-
the compiler, the books, the references, and the guides) to quickly find
443-
information about the language and compiler.
444-
* You can also use Rustdoc's built-in search feature to find documentation on
445-
types and functions within the crates you're looking at. You can also search
446-
by type signature! For example, searching for `* -> vec` should find all
447-
functions that return a `Vec<T>`.
448-
_Hint:_ Find more tips and keyboard shortcuts by typing `?` on any Rustdoc
449-
page!
450-
* Don't be afraid to ask! The Rust community is friendly and helpful.
451-
452-
[rustc dev guide]: about-this-guide.md
453-
[gdfrustc]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/
454-
[gsearchdocs]: https://www.google.com/search?q=site:doc.rust-lang.org+your+query+here
455-
[stddocs]: https://doc.rust-lang.org/std
456-
[rif]: http://internals.rust-lang.org
457-
[rr]: https://doc.rust-lang.org/book/README.html
458-
[rustforge]: https://forge.rust-lang.org/
459-
[tlgba]: https://tomlee.co/2014/04/a-more-detailed-tour-of-the-rust-compiler/
460-
[ro]: https://www.rustaceans.org/
461-
[rctd]: tests/intro.md
462-
[cheatsheet]: https://bors.rust-lang.org/
463-
[Miri]: https://github.com/rust-lang/miri
514+
This section has moved to the ["About this guide"][more-links] chapter.
515+
516+
[more-links]: ./about-this-guide.md#other-places-to-find-information

0 commit comments

Comments
 (0)