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