]>
Commit | Line | Data |
---|---|---|
6a06907d XL |
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. | |
29 | ||
30 | ## Bug Reports | |
31 | ||
32 | While bugs are unfortunate, they're a reality in software. We can't fix what we | |
33 | don't know about, so please report liberally. If you're not sure if something | |
34 | is a bug or not, feel free to file a bug anyway. | |
35 | ||
36 | **If you believe reporting your bug publicly represents a security risk to Rust users, | |
37 | please follow our [instructions for reporting security vulnerabilities][vuln]**. | |
38 | ||
39 | [vuln]: https://www.rust-lang.org/policies/security | |
40 | ||
41 | If you're using the nightly channel, please check if the bug exists in the | |
42 | latest toolchain before filing your bug. It might be fixed already. | |
43 | ||
44 | If you have the chance, before reporting a bug, please [search existing | |
45 | issues](https://github.com/rust-lang/rust/issues?q=is%3Aissue), | |
46 | as it's possible that someone else has already reported your error. This doesn't | |
47 | always work, and sometimes it's hard to know what to search for, so consider this | |
48 | extra credit. We won't mind if you accidentally file a duplicate report. | |
49 | ||
50 | Similarly, to help others who encountered the bug find your issue, consider | |
51 | filing an issue with a descriptive title, which contains information that might | |
52 | be unique to it. This can be the language or compiler feature used, the | |
53 | conditions that trigger the bug, or part of the error message if there is any. | |
54 | An example could be: **"impossible case reached" on lifetime inference for impl | |
55 | Trait in return position**. | |
56 | ||
57 | Opening an issue is as easy as following [this | |
58 | link](https://github.com/rust-lang/rust/issues/new/choose) and filling out the fields | |
59 | in the appropriate provided template. | |
60 | ||
61 | ## Pull Requests | |
62 | ||
63 | Pull requests (or PRs for short) are the primary mechanism we use to change Rust. | |
64 | GitHub itself has some [great documentation][about-pull-requests] on using the | |
65 | Pull Request feature. We use the "fork and pull" model [described here][development-models], | |
66 | where contributors push changes to their personal fork and create pull requests to | |
136023e0 XL |
67 | bring those changes into the source repository. We have more info about how to use git |
68 | when contributing to Rust under [the git section](./git.md). | |
6a06907d XL |
69 | |
70 | [about-pull-requests]: https://help.github.com/articles/about-pull-requests/ | |
71 | [development-models]: https://help.github.com/articles/about-collaborative-development-models/ | |
72 | ||
73 | All pull requests are reviewed by another person. We have a bot, | |
74 | [@rust-highfive][rust-highfive], that will automatically assign a random person | |
75 | to review your request. | |
76 | ||
77 | If you want to request that a specific person reviews your pull request, you | |
78 | can add an `r?` to the pull request description. For example, | |
79 | [Steve][steveklabnik] usually reviews documentation changes. So if you were to | |
80 | make a documentation change, add | |
81 | ||
82 | r? @steveklabnik | |
83 | ||
84 | to the end of the pull request description, and [@rust-highfive][rust-highfive] will assign | |
85 | [@steveklabnik][steveklabnik] instead of a random person. This is entirely optional. | |
86 | ||
87 | In addition to being reviewed by a human, pull requests are automatically tested | |
88 | thanks to continuous integration (CI). Basically, every time you open and update | |
89 | a pull request, CI builds the compiler and tests it against the | |
90 | [compiler test suite][rctd], and also performs other tests such as checking that | |
91 | your pull request is in compliance with Rust's style guidelines. | |
92 | ||
93 | Running continuous integration tests allows PR authors to catch mistakes early | |
94 | without going through a first review cycle, and also helps reviewers stay aware | |
95 | of the status of a particular pull request. | |
96 | ||
97 | Rust has plenty of CI capacity, and you should never have to worry about wasting | |
98 | computational resources each time you push a change. It is also perfectly fine | |
99 | (and even encouraged!) to use the CI to test your changes if it can help your | |
100 | productivity. In particular, we don't recommend running the full `x.py test` suite locally, | |
101 | since it takes a very long time to execute. | |
102 | ||
103 | After someone has reviewed your pull request, they will leave an annotation | |
104 | on the pull request with an `r+`. It will look something like this: | |
105 | ||
106 | @bors r+ | |
107 | ||
108 | This tells [@bors], our lovable integration bot, that your pull request has | |
109 | been approved. The PR then enters the [merge queue][merge-queue], where [@bors] | |
110 | will run *all* the tests on *every* platform we support. If it all works out, | |
111 | [@bors] will merge your code into `master` and close the pull request. | |
112 | ||
113 | Depending on the scale of the change, you may see a slightly different form of `r+`: | |
114 | ||
115 | @bors r+ rollup | |
116 | ||
117 | The additional `rollup` tells [@bors] that this change should always be "rolled up". | |
118 | Changes that are rolled up are tested and merged alongside other PRs, to | |
119 | speed the process up. Typically only small changes that are expected not to conflict | |
120 | with one another are marked as "always roll up". | |
121 | ||
122 | [rust-highfive]: https://github.com/rust-highfive | |
123 | [steveklabnik]: https://github.com/steveklabnik | |
124 | [@bors]: https://github.com/bors | |
125 | [merge-queue]: https://bors.rust-lang.org/queue/rust | |
126 | ||
127 | ### Opening a PR | |
128 | ||
129 | You are now ready to file a pull request? Great! Here are a few points you | |
130 | should be aware of. | |
131 | ||
132 | All pull requests should be filed against the `master` branch, except in very | |
133 | particular scenarios. Unless you know for sure that you should target another | |
134 | branch, `master` will be the right choice (it's also the default). | |
135 | ||
136 | Make sure your pull request is in compliance with Rust's style guidelines by running | |
137 | ||
138 | $ ./x.py test tidy --bless | |
139 | ||
140 | We recommend to make this check before every pull request (and every new commit | |
141 | in a pull request); you can add [git hooks](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks) | |
142 | before every push to make sure you never forget to make this check. The | |
143 | CI will also run tidy and will fail if tidy fails. | |
144 | ||
145 | Rust follows a _no merge-commit policy_, meaning, when you encounter merge | |
146 | conflicts you are expected to always rebase instead of merging. E.g. always use | |
147 | rebase when bringing the latest changes from the master branch to your feature | |
136023e0 | 148 | branch. |
6a06907d | 149 | |
17df50a5 XL |
150 | If you encounter merge conflicts or when a reviewer asks you to perform some |
151 | changes, your PR will get marked as `S-waiting-on-author`. When you resolve | |
152 | them, you should use `@rustbot` to mark it as `S-waiting-on-review`: | |
153 | ||
154 | @rustbot label -S-waiting-on-author +S-waiting-on-review | |
155 | ||
6a06907d XL |
156 | See [this chapter][labeling] for more details. |
157 | ||
158 | GitHub allows [closing issues using keywords][closing-keywords]. This feature | |
159 | should be used to keep the issue tracker tidy. However, it is generally preferred | |
160 | to put the "closes #123" text in the PR description rather than the issue commit; | |
161 | particularly during rebasing, citing the issue number in the commit can "spam" | |
162 | the issue in question. | |
163 | ||
164 | [labeling]: ./rustbot.md#issue-relabeling | |
165 | [closing-keywords]: https://help.github.com/en/articles/closing-issues-using-keywords | |
166 | ||
167 | ### External Dependencies (subtree) | |
168 | ||
169 | As a developer to this repository, you don't have to treat the following external projects | |
170 | differently from other crates that are directly in this repo: | |
171 | ||
17df50a5 XL |
172 | * [Clippy](https://github.com/rust-lang/rust-clippy) |
173 | * [rustfmt](https://github.com/rust-lang/rustfmt) | |
6a06907d XL |
174 | |
175 | They are just regular files and directories. This is in contrast to `submodule` dependencies | |
176 | (see below for those). Only tool authors will actually use any operations here. | |
177 | ||
178 | #### Synchronizing a subtree | |
179 | ||
180 | There are two synchronization directions: `subtree push` and `subtree pull`. | |
181 | ||
182 | ``` | |
183 | git subtree push -P src/tools/clippy git@github.com:your-github-name/rust-clippy sync-from-rust | |
184 | ``` | |
185 | ||
186 | takes all the changes that | |
187 | happened to the copy in this repo and creates commits on the remote repo that match the local | |
188 | changes. Every local commit that touched the subtree causes a commit on the remote repo, but is | |
189 | modified to move the files from the specified directory to the tool repo root. | |
190 | ||
191 | Make sure to not pick the `master` branch on the tool repo, so you can open a normal PR to the tool | |
192 | to merge that subrepo push. | |
193 | ||
194 | ``` | |
195 | git subtree pull -P src/tools/clippy https://github.com/rust-lang/rust-clippy master | |
196 | ``` | |
197 | ||
198 | takes all changes since the last `subtree pull` from the tool repo | |
199 | and adds these commits to the rustc repo + a merge commit that moves the tool changes into | |
200 | the specified directory in the rust repository. | |
201 | ||
202 | It is recommended that you always do a push first and get that merged to the tool master branch. | |
203 | Then, when you do a pull, the merge works without conflicts. | |
204 | While it's definitely possible to resolve conflicts during a pull, you may have to redo the conflict | |
205 | resolution if your PR doesn't get merged fast enough and there are new conflicts. Do not try to | |
206 | rebase the result of a `git subtree pull`, rebasing merge commits is a bad idea in general. | |
207 | ||
208 | You always need to specify the `-P` prefix to the subtree directory and the corresponding remote | |
209 | repository. If you specify the wrong directory or repository | |
210 | you'll get very fun merges that try to push the wrong directory to the wrong remote repository. | |
211 | Luckily you can just abort this without any consequences by throwing away either the pulled commits | |
212 | in rustc or the pushed branch on the remote and try again. It is usually fairly obvious | |
213 | that this is happening because you suddenly get thousands of commits that want to be synchronized. | |
214 | ||
215 | #### Creating a new subtree dependency | |
216 | ||
217 | If you want to create a new subtree dependency from an existing repository, call (from this | |
218 | repository's root directory!) | |
219 | ||
220 | ``` | |
221 | git subtree add -P src/tools/clippy https://github.com/rust-lang/rust-clippy.git master | |
222 | ``` | |
223 | ||
224 | This will create a new commit, which you may not rebase under any circumstances! Delete the commit | |
225 | and redo the operation if you need to rebase. | |
226 | ||
227 | Now you're done, the `src/tools/clippy` directory behaves as if Clippy were | |
228 | part of the rustc monorepo, so no one but you (or others that synchronize | |
229 | subtrees) actually needs to use `git subtree`. | |
230 | ||
231 | ||
232 | ### External Dependencies (submodules) | |
233 | ||
234 | Currently building Rust will also build the following external projects: | |
235 | ||
236 | * [miri](https://github.com/rust-lang/miri) | |
6a06907d XL |
237 | * [rls](https://github.com/rust-lang/rls/) |
238 | ||
239 | We allow breakage of these tools in the nightly channel. Maintainers of these | |
240 | projects will be notified of the breakages and should fix them as soon as | |
241 | possible. | |
242 | ||
243 | After the external is fixed, one could add the changes with | |
244 | ||
245 | ```sh | |
246 | git add path/to/submodule | |
247 | ``` | |
248 | ||
249 | outside the submodule. | |
250 | ||
251 | In order to prepare your tool-fixing PR, you can run the build locally by doing | |
252 | `./x.py build src/tools/TOOL`. If you will be editing the sources | |
253 | there, you may wish to set `submodules = false` in the `config.toml` | |
254 | to prevent `x.py` from resetting to the original branch. | |
255 | ||
256 | Breakage is not allowed in the beta and stable channels, and must be addressed | |
257 | before the PR is merged. | |
258 | ||
259 | #### Breaking Tools Built With The Compiler | |
260 | ||
17df50a5 XL |
261 | Rust's build system builds a number of tools that make use of the internals of |
262 | the compiler and that are hosted in a separate repository, and included in Rust | |
263 | via git submodules. This includes [RLS](https://github.com/rust-lang/rls) and | |
264 | [Miri](https://github.com/rust-lang/Miri). If these tools break because of your | |
265 | changes, you may run into a sort of "chicken and egg" problem. These tools rely | |
266 | on the latest compiler to be built so you can't update them (in their own | |
267 | repositories) to reflect your changes to the compiler until those changes are | |
268 | merged into the compiler. At the same time, you can't get your changes merged | |
269 | into the compiler because the rust-lang/rust build won't pass until those tools | |
270 | build and pass their tests. | |
271 | ||
272 | Luckily, a feature was | |
273 | [added to Rust's build](https://github.com/rust-lang/rust/issues/45861) to make | |
274 | all of this easy to handle. The idea is that we allow these tools to be | |
275 | "broken", so that the rust-lang/rust build passes without trying to build them, | |
276 | then land the change in the compiler, and go update the tools that you | |
277 | broke. Some tools will require waiting for a nightly release before this can | |
278 | happen, while others use the builds uploaded after each bors merge and thus can | |
279 | be updated immediately (check the tool's documentation for details). Once you're | |
280 | done and the tools are working again, you go back in the compiler and update the | |
281 | tools so they can be distributed again. | |
6a06907d XL |
282 | |
283 | This should avoid a bunch of synchronization dances and is also much easier on contributors as | |
17df50a5 | 284 | there's no need to block on rls/miri/other tools changes going upstream. |
6a06907d XL |
285 | |
286 | Here are those same steps in detail: | |
287 | ||
288 | 1. (optional) First, if it doesn't exist already, create a `config.toml` by copying | |
289 | `config.toml.example` in the root directory of the Rust repository. | |
290 | Set `submodules = false` in the `[build]` section. This will prevent `x.py` | |
291 | from resetting to the original branch after you make your changes. If you | |
292 | need to [update any submodules to their latest versions](#updating-submodules), | |
293 | see the section of this file about that for more information. | |
17df50a5 XL |
294 | 2. (optional) Run `./x.py test src/tools/rls` (substituting the submodule |
295 | that broke for `rls`). Fix any errors in the submodule (and possibly others). | |
6a06907d XL |
296 | 3. (optional) Make commits for your changes and send them to upstream repositories as a PR. |
297 | 4. (optional) Maintainers of these submodules will **not** merge the PR. The PR can't be | |
298 | merged because CI will be broken. You'll want to write a message on the PR referencing | |
299 | your change, and how the PR should be merged once your change makes it into a nightly. | |
300 | 5. Wait for your PR to merge. | |
301 | 6. Wait for a nightly | |
302 | 7. (optional) Help land your PR on the upstream repository now that your changes are in nightly. | |
303 | 8. (optional) Send a PR to rust-lang/rust updating the submodule. | |
304 | ||
305 | #### Updating submodules | |
306 | ||
17df50a5 | 307 | These instructions are specific to updating `rls`, however they may apply |
6a06907d XL |
308 | to the other submodules as well. Please help by improving these instructions |
309 | if you find any discrepancies or special cases that need to be addressed. | |
310 | ||
17df50a5 | 311 | To update the `rls` submodule, start by running the appropriate |
6a06907d XL |
312 | [`git submodule` command](https://git-scm.com/book/en/v2/Git-Tools-Submodules). |
313 | For example, to update to the latest commit on the remote master branch, | |
314 | you may want to run: | |
315 | ``` | |
17df50a5 | 316 | git submodule update --remote src/tools/rls |
6a06907d XL |
317 | ``` |
318 | If you run `./x.py build` now, and you are lucky, it may just work. If you see | |
319 | an error message about patches that did not resolve to any crates, you will need | |
320 | to complete a few more steps which are outlined with their rationale below. | |
321 | ||
322 | *(This error may change in the future to include more information.)* | |
323 | ``` | |
17df50a5 | 324 | error: failed to resolve patches for `https://github.com/rust-lang/rls` |
6a06907d XL |
325 | |
326 | Caused by: | |
17df50a5 | 327 | patch for `rls` in `https://github.com/rust-lang/rls` did not resolve to any crates |
6a06907d XL |
328 | failed to run: ~/rust/build/x86_64-unknown-linux-gnu/stage0/bin/cargo build --manifest-path ~/rust/src/bootstrap/Cargo.toml |
329 | ``` | |
330 | ||
331 | The [`[patch]`][patchsec] section of `Cargo.toml` can be very useful for | |
332 | testing. In addition to that, you should read the [Overriding | |
333 | dependencies][overriding] section of the documentation. | |
334 | ||
335 | [patchsec]: http://doc.crates.io/manifest.html#the-patch-section | |
336 | [overriding]: http://doc.crates.io/specifying-dependencies.html#overriding-dependencies | |
337 | ||
338 | Specifically, the following [section in Overriding dependencies][testingbugfix] | |
339 | reveals what the problem is: | |
340 | ||
341 | [testingbugfix]: http://doc.crates.io/specifying-dependencies.html#testing-a-bugfix | |
342 | ||
343 | > Next up we need to ensure that our lock file is updated to use this new | |
344 | > version of uuid so our project uses the locally checked out copy instead of | |
345 | > one from crates.io. The way `[patch]` works is that it'll load the dependency | |
346 | > at ../path/to/uuid and then whenever crates.io is queried for versions of | |
347 | > uuid it'll also return the local version. | |
348 | > | |
349 | > This means that the version number of the local checkout is significant and | |
350 | > will affect whether the patch is used. Our manifest declared uuid = "1.0" | |
351 | > which means we'll only resolve to >= 1.0.0, < 2.0.0, and Cargo's greedy | |
352 | > resolution algorithm also means that we'll resolve to the maximum version | |
353 | > within that range. Typically this doesn't matter as the version of the git | |
354 | > repository will already be greater or match the maximum version published on | |
355 | > crates.io, but it's important to keep this in mind! | |
356 | ||
357 | This says that when we updated the submodule, the version number in our | |
17df50a5 | 358 | `src/tools/rls/Cargo.toml` changed. The new version is different from |
6a06907d XL |
359 | the version in `Cargo.lock`, so the build can no longer continue. |
360 | ||
361 | To resolve this, we need to update `Cargo.lock`. Luckily, cargo provides a | |
362 | command to do this easily. | |
363 | ||
364 | ``` | |
17df50a5 | 365 | $ cargo update -p rls |
6a06907d XL |
366 | ``` |
367 | ||
368 | This should change the version listed in `Cargo.lock` to the new version you updated | |
369 | the submodule to. Running `./x.py build` should work now. | |
370 | ||
371 | ## Writing Documentation | |
372 | ||
373 | Documentation improvements are very welcome. The source of `doc.rust-lang.org` | |
374 | is located in [`src/doc`] in the tree, and standard API documentation is generated | |
375 | from the source code itself (e.g. [`lib.rs`]). Documentation pull requests function | |
376 | in the same way as other pull requests. | |
377 | ||
378 | [`src/doc`]: https://github.com/rust-lang/rust/tree/master/src/doc | |
379 | [`lib.rs`]: https://github.com/rust-lang/rust/blob/master/library/std/src/lib.rs#L1 | |
380 | ||
381 | To find documentation-related issues, sort by the [T-doc label][tdoc]. | |
382 | ||
383 | [tdoc]: https://github.com/rust-lang/rust/issues?q=is%3Aopen%20is%3Aissue%20label%3AT-doc | |
384 | ||
385 | You can find documentation style guidelines in [RFC 1574][rfc1574]. | |
386 | ||
387 | [rfc1574]: https://github.com/rust-lang/rfcs/blob/master/text/1574-more-api-documentation-conventions.md#appendix-a-full-conventions-text | |
388 | ||
389 | In many cases, you don't need a full `./x.py doc --stage 2`, which will build | |
390 | the entire stage 2 compiler and compile the various books published on | |
391 | [doc.rust-lang.org][docs]. When updating documentation for the standard library, | |
392 | first try `./x.py doc library/std`. If that fails, or if you need to | |
393 | see the output from the latest version of `rustdoc`, add `--stage 1`. | |
394 | Results should appear in `build/$TARGET/doc`. | |
395 | ||
396 | [docs]: https://doc.rust-lang.org | |
397 | ||
398 | You can also use `rustdoc` directly to check small fixes. For example, | |
399 | `rustdoc src/doc/reference.md` will render reference to `doc/reference.html`. | |
400 | The CSS might be messed up, but you can verify that the HTML is right. | |
401 | ||
402 | ### Contributing to rustc-dev-guide | |
403 | ||
404 | Contributions to the [rustc-dev-guide][rdg] are always welcome, and can be made directly at | |
405 | [the rust-lang/rustc-dev-guide repo][rdgrepo]. | |
406 | The issue tracker in that repo is also a great way to find things that need doing. | |
407 | There are issues for beginners and advanced compiler devs alike! | |
408 | ||
409 | Just a few things to keep in mind: | |
410 | ||
411 | - Please limit line length to 100 characters. This is enforced by CI, and you can run the checks | |
412 | locally with `ci/check_line_lengths.sh`. | |
413 | ||
414 | - When contributing text to the guide, please contextualize the information with some time period | |
415 | and/or a reason so that the reader knows how much to trust or mistrust the information. | |
416 | Aim to provide a reasonable amount of context, possibly including but not limited to: | |
417 | ||
418 | - A reason for why the data may be out of date other than "change", as change is a constant across | |
419 | the project. | |
420 | ||
421 | - The date the comment was added, e.g. instead of writing _"Currently, ..."_ | |
422 | or _"As of now, ..."_, consider writing | |
423 | _"As of January 2021, ..."_. | |
424 | Try to format the date as `<MONTH> <YEAR>` to ease search. | |
425 | ||
426 | - Additionally, include a machine-readable comment of the form `<!-- date: | |
427 | 2021-01 -->` (if the current month is January 2021). We have an automated | |
428 | tool that uses these (in `ci/date-check`). | |
429 | ||
430 | So, for the month of January 2021, the comment would look like: `As of <!-- | |
431 | date: 2021-01 --> January 2021`. Make sure to put the comment *between* `as of` | |
432 | and `January 2021`; see [PR #1066][rdg#1066] for the rationale. | |
433 | ||
434 | - A link to a relevant WG, tracking issue, `rustc` rustdoc page, or similar, that may provide | |
435 | further explanation for the change process or a way to verify that the information is not | |
436 | outdated. | |
437 | ||
438 | - If a text grows rather long (more than a few page scrolls) or complicated (more than four | |
439 | subsections) it might benefit from having a Table of Contents at the beginning, which you can | |
440 | auto-generate by including the `<!-- toc -->` marker. | |
441 | ||
442 | [rdg]: https://rustc-dev-guide.rust-lang.org/ | |
443 | [rdgrepo]: https://github.com/rust-lang/rustc-dev-guide | |
444 | [rdg#1066]: https://github.com/rust-lang/rustc-dev-guide/pull/1066 | |
445 | ||
446 | ## Issue Triage | |
447 | ||
448 | Sometimes, an issue will stay open, even though the bug has been fixed. And | |
449 | sometimes, the original bug may go stale because something has changed in the | |
450 | meantime. | |
451 | ||
452 | It can be helpful to go through older bug reports and make sure that they are | |
453 | still valid. Load up an older issue, double check that it's still true, and | |
454 | leave a comment letting us know if it is or is not. The [least recently | |
455 | updated sort][lru] is good for finding issues like this. | |
456 | ||
457 | [Thanks to `@rustbot`][rustbot], anyone can help triage issues by adding | |
458 | appropriate labels to issues that haven't been triaged yet: | |
459 | ||
460 | * Yellow, **A**-prefixed labels state which **area** of the project an issue | |
461 | relates to. | |
462 | ||
463 | * Magenta, **B**-prefixed labels identify bugs which are **blockers**. | |
464 | ||
465 | * Dark blue, **beta-** labels track changes which need to be backported into | |
466 | the beta branches. | |
467 | ||
468 | * Light purple, **C**-prefixed labels represent the **category** of an issue. | |
469 | ||
470 | * Green, **E**-prefixed labels explain the level of **experience** necessary | |
471 | to fix the issue. | |
472 | ||
473 | * The dark blue **final-comment-period** label marks bugs that are using the | |
474 | RFC signoff functionality of [rfcbot] and are currently in the final | |
475 | comment period. | |
476 | ||
477 | * Red, **I**-prefixed labels indicate the **importance** of the issue. The | |
478 | [I-nominated][inom] label indicates that an issue has been nominated for | |
479 | discussion at the next meeting of the team tagged using a | |
480 | **T**-prefixed label. Similarly, the [I-prioritize][ipri] indicates | |
481 | that an issue has been requested to be prioritized by the appropriate | |
482 | team. | |
483 | ||
484 | * The purple **metabug** label marks lists of bugs collected by other | |
485 | categories. | |
486 | ||
487 | * Purple gray, **O**-prefixed labels are the **operating system** or platform | |
488 | that this issue is specific to. | |
489 | ||
490 | * Orange, **P**-prefixed labels indicate a bug's **priority**. These labels | |
491 | can be assigned by anyone that understand the issue and is able to | |
492 | prioritize it, and replace the [I-prioritize][ipri] label. | |
493 | ||
494 | * The gray **proposed-final-comment-period** label marks bugs that are using | |
495 | the RFC signoff functionality of [rfcbot] and are currently awaiting | |
496 | signoff of all team members in order to enter the final comment period. | |
497 | ||
498 | * Pink, **regression**-prefixed labels track regressions from stable to the | |
499 | release channels. | |
500 | ||
501 | * The light orange **relnotes** label marks issues that should be documented in | |
502 | the release notes of the next release. | |
503 | ||
504 | * Gray, **S**-prefixed labels are used for tracking the **status** of pull | |
505 | requests. | |
506 | ||
507 | * Blue, **T**-prefixed bugs denote which **team** the issue belongs to. | |
508 | ||
509 | If you're looking for somewhere to start, check out the [E-easy][eeasy] tag. | |
510 | ||
511 | [rustbot]: ./rustbot.md | |
512 | [inom]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AI-nominated | |
513 | [ipri]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AI-prioritize | |
514 | [eeasy]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AE-easy | |
515 | [lru]: https://github.com/rust-lang/rust/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-asc | |
516 | [rfcbot]: https://github.com/anp/rfcbot-rs/ | |
517 | ||
518 | ## Out-of-tree Contributions | |
519 | ||
520 | There are a number of other ways to contribute to Rust that don't deal with | |
521 | rust-lang/rust: | |
522 | ||
523 | * Answer questions in the _Get Help!_ channels on the [Rust Discord | |
524 | server][rust-discord], on [users.rust-lang.org][users], or on | |
525 | [StackOverflow][so]. | |
526 | * Participate in the [RFC process](https://github.com/rust-lang/rfcs). | |
527 | * Find a [requested community library][community-library], build it, and publish | |
528 | it to [Crates.io](http://crates.io). Easier said than done, but very, very | |
529 | valuable! | |
530 | ||
531 | [rust-discord]: https://discord.gg/rust-lang | |
532 | [users]: https://users.rust-lang.org/ | |
533 | [so]: http://stackoverflow.com/questions/tagged/rust | |
534 | [community-library]: https://github.com/rust-lang/rfcs/labels/A-community-library | |
535 | ||
536 | ## Helpful Links and Information | |
537 | ||
538 | For people new to Rust, and just starting to contribute, or even for | |
539 | more seasoned developers, some useful places to look for information | |
540 | are: | |
541 | ||
542 | * This guide contains information about how various parts of the | |
543 | compiler work and how to contribute to the compiler | |
544 | * [Rust Forge][rustforge] contains additional documentation, including | |
545 | write-ups of how to achieve common tasks | |
546 | * The [Rust Internals forum][rif], a place to ask questions and | |
547 | discuss Rust's internals | |
548 | * The [generated documentation for Rust's compiler][gdfrustc] | |
549 | * The [Rust reference][rr], even though it doesn't specifically talk about | |
550 | Rust's internals, is a great resource nonetheless | |
551 | * Although out of date, [Tom Lee's great blog article][tlgba] is very helpful | |
552 | * [rustaceans.org][ro] is helpful, but mostly dedicated to IRC | |
553 | * The [Rust Compiler Testing Docs][rctd] | |
554 | * For [@bors], [this cheat sheet][cheatsheet] is helpful | |
555 | * Google is always helpful when programming. | |
556 | You can [search all Rust documentation][gsearchdocs] (the standard library, | |
557 | the compiler, the books, the references, and the guides) to quickly find | |
558 | information about the language and compiler. | |
559 | * You can also use Rustdoc's built-in search feature to find documentation on | |
560 | types and functions within the crates you're looking at. You can also search | |
561 | by type signature! For example, searching for `* -> vec` should find all | |
562 | functions that return a `Vec<T>`. | |
563 | _Hint:_ Find more tips and keyboard shortcuts by typing `?` on any Rustdoc | |
564 | page! | |
565 | * Don't be afraid to ask! The Rust community is friendly and helpful. | |
566 | ||
567 | [rustc dev guide]: https://rustc-dev-guide.rust-lang.org/about-this-guide.html | |
568 | [gdfrustc]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ | |
569 | [gsearchdocs]: https://www.google.com/search?q=site:doc.rust-lang.org+your+query+here | |
570 | [stddocs]: https://doc.rust-lang.org/std | |
571 | [rif]: http://internals.rust-lang.org | |
572 | [rr]: https://doc.rust-lang.org/book/README.html | |
573 | [rustforge]: https://forge.rust-lang.org/ | |
574 | [tlgba]: https://tomlee.co/2014/04/a-more-detailed-tour-of-the-rust-compiler/ | |
575 | [ro]: https://www.rustaceans.org/ | |
576 | [rctd]: https://rustc-dev-guide.rust-lang.org/tests/intro.html | |
577 | [cheatsheet]: https://bors.rust-lang.org/ |