]>
Commit | Line | Data |
---|---|---|
85aaf69f | 1 | # Contributing to Rust |
1a4d82fc | 2 | |
85aaf69f SL |
3 | Thank you for your interest in contributing to Rust! There are many ways to |
4 | contribute, and we appreciate all of them. This document is a bit long, so here's | |
5 | links to the major sections: | |
1a4d82fc | 6 | |
85aaf69f SL |
7 | * [Feature Requests](#feature-requests) |
8 | * [Bug Reports](#bug-reports) | |
9 | * [Pull Requests](#pull-requests) | |
10 | * [Writing Documentation](#writing-documentation) | |
11 | * [Issue Triage](#issue-triage) | |
12 | * [Out-of-tree Contributions](#out-of-tree-contributions) | |
1a4d82fc | 13 | |
85aaf69f SL |
14 | If you have questions, please make a post on [internals.rust-lang.org][internals] or |
15 | hop on [#rust-internals][pound-rust-internals]. | |
1a4d82fc | 16 | |
c34b1796 | 17 | As a reminder, all contributors are expected to follow our [Code of Conduct][coc]. |
1a4d82fc | 18 | |
85aaf69f SL |
19 | [pound-rust-internals]: http://chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust-internals |
20 | [internals]: http://internals.rust-lang.org | |
21 | [coc]: http://www.rust-lang.org/conduct.html | |
1a4d82fc | 22 | |
85aaf69f | 23 | ## Feature Requests |
1a4d82fc | 24 | |
85aaf69f SL |
25 | To request a change to the way that the Rust language works, please open an |
26 | issue in the [RFCs repository](https://github.com/rust-lang/rfcs/issues/new) | |
27 | rather than this one. New features and other significant language changes | |
28 | must go through the RFC process. | |
1a4d82fc | 29 | |
85aaf69f | 30 | ## Bug Reports |
1a4d82fc | 31 | |
85aaf69f SL |
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. | |
1a4d82fc | 35 | |
85aaf69f SL |
36 | If you have the chance, before reporting a bug, please [search existing |
37 | issues](https://github.com/rust-lang/rust/search?q=&type=Issues&utf8=%E2%9C%93), | |
38 | as it's possible that someone else has already reported your error. This doesn't | |
39 | always work, and sometimes it's hard to know what to search for, so consider this | |
40 | extra credit. We won't mind if you accidentally file a duplicate report. | |
1a4d82fc | 41 | |
85aaf69f SL |
42 | Opening an issue is as easy as following [this |
43 | link](https://github.com/rust-lang/rust/issues/new) and filling out the fields. | |
44 | Here's a template that you can use to file a bug, though it's not necessary to | |
45 | use it exactly: | |
1a4d82fc | 46 | |
85aaf69f SL |
47 | <short summary of the bug> |
48 | ||
49 | I tried this code: | |
50 | ||
51 | <code sample that causes the bug> | |
52 | ||
53 | I expected to see this happen: <explanation> | |
54 | ||
55 | Instead, this happened: <explanation> | |
56 | ||
57 | ## Meta | |
58 | ||
59 | `rustc --version --verbose`: | |
60 | ||
61 | Backtrace: | |
62 | ||
63 | All three components are important: what you did, what you expected, what | |
64 | happened instead. Please include the output of `rustc --version --verbose`, | |
65 | which includes important information about what platform you're on, what | |
66 | version of Rust you're using, etc. | |
67 | ||
68 | Sometimes, a backtrace is helpful, and so including that is nice. To get | |
69 | a backtrace, set the `RUST_BACKTRACE` environment variable. The easiest way | |
70 | to do this is to invoke `rustc` like this: | |
71 | ||
72 | ```bash | |
73 | $ RUST_BACKTRACE=1 rustc ... | |
1a4d82fc JJ |
74 | ``` |
75 | ||
85aaf69f | 76 | ## Pull Requests |
1a4d82fc | 77 | |
85aaf69f SL |
78 | Pull requests are the primary mechanism we use to change Rust. GitHub itself |
79 | has some [great documentation][pull-requests] on using the Pull Request | |
80 | feature. We use the 'fork and pull' model described there. | |
1a4d82fc | 81 | |
85aaf69f SL |
82 | [pull-requests]: https://help.github.com/articles/using-pull-requests/ |
83 | ||
84 | Please make pull requests against the `master` branch. | |
85 | ||
86 | All pull requests are reviewed by another person. We have a bot, | |
62682a34 SL |
87 | @rust-highfive, that will automatically assign a random person to review your |
88 | request. | |
85aaf69f SL |
89 | |
90 | If you want to request that a specific person reviews your pull request, | |
91 | you can add an `r?` to the message. For example, Steve usually reviews | |
92 | documentation changes. So if you were to make a documentation change, add | |
93 | ||
94 | r? @steveklabnik | |
95 | ||
96 | to the end of the message, and @rust-highfive will assign @steveklabnik instead | |
97 | of a random person. This is entirely optional. | |
98 | ||
99 | After someone has reviewed your pull request, they will leave an annotation | |
100 | on the pull request with an `r+`. It will look something like this: | |
101 | ||
102 | @bors: r+ 38fe8d2 | |
103 | ||
104 | This tells @bors, our lovable integration bot, that your pull request has | |
105 | been approved. The PR then enters the [merge queue][merge-queue], where @bors | |
106 | will run all the tests on every platform we support. If it all works out, | |
107 | @bors will merge your code into `master` and close the pull request. | |
108 | ||
109 | [merge-queue]: http://buildbot.rust-lang.org/homu/queue/rust | |
110 | ||
111 | ## Writing Documentation | |
112 | ||
113 | Documentation improvements are very welcome. The source of `doc.rust-lang.org` | |
114 | is located in `src/doc` in the tree, and standard API documentation is generated | |
115 | from the source code itself. | |
116 | ||
117 | Documentation pull requests function in the same as other pull requests, though | |
118 | you may see a slightly different form of `r+`: | |
119 | ||
120 | @bors: r+ 38fe8d2 rollup | |
121 | ||
122 | That additional `rollup` tells @bors that this change is eligible for a 'rollup'. | |
123 | To save @bors some work, and to get small changes through more quickly, when | |
124 | @bors attempts to merge a commit that's rollup-eligible, it will also merge | |
125 | the other rollup-eligible patches too, and they'll get tested and merged at | |
126 | the same time. | |
127 | ||
62682a34 SL |
128 | To find documentation-related issues, sort by the [A-docs label][adocs]. |
129 | ||
130 | [adocs]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AA-docs | |
131 | ||
85aaf69f SL |
132 | ## Issue Triage |
133 | ||
134 | Sometimes, an issue will stay open, even though the bug has been fixed. And | |
135 | sometimes, the original bug may go stale because something has changed in the | |
136 | meantime. | |
137 | ||
138 | It can be helpful to go through older bug reports and make sure that they are | |
139 | still valid. Load up an older issue, double check that it's still true, and | |
62682a34 SL |
140 | leave a comment letting us know if it is or is not. The [least recently |
141 | updated sort][lru] is good for finding issues like this. | |
142 | ||
143 | Contributors with sufficient permissions on the Rust repo can help by adding | |
144 | labels to triage issues: | |
145 | ||
146 | * Yellow, **A**-prefixed labels state which **area** of the project an issue | |
147 | relates to. | |
148 | ||
149 | * Magenta, **B**-prefixed labels identify bugs which **belong** elsewhere. | |
150 | ||
151 | * Green, **E**-prefixed labels explain the level of **experience** necessary | |
152 | to fix the issue. | |
153 | ||
154 | * Red, **I**-prefixed labels indicate the **importance** of the issue. The | |
155 | [I-nominated][inom] label indicates that an issue has been nominated for | |
156 | prioritizing at the next triage meeting. | |
157 | ||
158 | * Orange, **P**-prefixed labels indicate a bug's **priority**. These labels | |
159 | are only assigned during triage meetings, and replace the [I-nominated][inom] | |
160 | label. | |
161 | ||
162 | * Blue, **T**-prefixed bugs denote which **team** the issue belongs to. | |
163 | ||
164 | * Dark blue, **beta-** labels track changes which need to be backported into | |
165 | the beta branches. | |
166 | ||
167 | * The purple **metabug** label marks lists of bugs collected by other | |
168 | categories. | |
169 | ||
170 | If you're looking for somewhere to start, check out the [E-easy][eeasy] tag. | |
85aaf69f | 171 | |
62682a34 SL |
172 | [inom]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AI-nominated |
173 | [eeasy]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AE-easy | |
85aaf69f SL |
174 | [lru]: https://github.com/rust-lang/rust/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-asc |
175 | ||
176 | ## Out-of-tree Contributions | |
177 | ||
178 | There are a number of other ways to contribute to Rust that don't deal with | |
179 | this repository. | |
180 | ||
181 | Answer questions in [#rust][pound-rust], or on [users.rust-lang.org][users], | |
182 | or on [StackOverflow][so]. | |
183 | ||
184 | Participate in the [RFC process](https://github.com/rust-lang/rfcs). | |
185 | ||
186 | Find a [requested community library][community-library], build it, and publish | |
187 | it to [Crates.io](http://crates.io). Easier said than done, but very, very | |
188 | valuable! | |
1a4d82fc | 189 | |
85aaf69f SL |
190 | [pound-rust]: http://chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust |
191 | [users]: http://users.rust-lang.org/ | |
192 | [so]: http://stackoverflow.com/questions/tagged/rust | |
193 | [community-library]: https://github.com/rust-lang/rfcs/labels/A-community-library |