]>
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) | |
e9174d1e | 13 | * [Helpful Links and Information](#helpful-links-and-information) |
1a4d82fc | 14 | |
85aaf69f SL |
15 | If you have questions, please make a post on [internals.rust-lang.org][internals] or |
16 | hop on [#rust-internals][pound-rust-internals]. | |
1a4d82fc | 17 | |
c34b1796 | 18 | As a reminder, all contributors are expected to follow our [Code of Conduct][coc]. |
1a4d82fc | 19 | |
85aaf69f | 20 | [pound-rust-internals]: http://chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust-internals |
e9174d1e SL |
21 | [internals]: https://internals.rust-lang.org |
22 | [coc]: https://www.rust-lang.org/conduct.html | |
1a4d82fc | 23 | |
85aaf69f | 24 | ## Feature Requests |
1a4d82fc | 25 | |
85aaf69f SL |
26 | To request a change to the way that the Rust language works, please open an |
27 | issue in the [RFCs repository](https://github.com/rust-lang/rfcs/issues/new) | |
28 | rather than this one. New features and other significant language changes | |
29 | must go through the RFC process. | |
1a4d82fc | 30 | |
85aaf69f | 31 | ## Bug Reports |
1a4d82fc | 32 | |
85aaf69f SL |
33 | While bugs are unfortunate, they're a reality in software. We can't fix what we |
34 | don't know about, so please report liberally. If you're not sure if something | |
35 | is a bug or not, feel free to file a bug anyway. | |
1a4d82fc | 36 | |
85aaf69f SL |
37 | If you have the chance, before reporting a bug, please [search existing |
38 | issues](https://github.com/rust-lang/rust/search?q=&type=Issues&utf8=%E2%9C%93), | |
39 | as it's possible that someone else has already reported your error. This doesn't | |
40 | always work, and sometimes it's hard to know what to search for, so consider this | |
41 | extra credit. We won't mind if you accidentally file a duplicate report. | |
1a4d82fc | 42 | |
85aaf69f SL |
43 | Opening an issue is as easy as following [this |
44 | link](https://github.com/rust-lang/rust/issues/new) and filling out the fields. | |
45 | Here's a template that you can use to file a bug, though it's not necessary to | |
46 | use it exactly: | |
1a4d82fc | 47 | |
85aaf69f SL |
48 | <short summary of the bug> |
49 | ||
50 | I tried this code: | |
51 | ||
52 | <code sample that causes the bug> | |
53 | ||
54 | I expected to see this happen: <explanation> | |
55 | ||
56 | Instead, this happened: <explanation> | |
57 | ||
58 | ## Meta | |
59 | ||
60 | `rustc --version --verbose`: | |
61 | ||
62 | Backtrace: | |
63 | ||
64 | All three components are important: what you did, what you expected, what | |
65 | happened instead. Please include the output of `rustc --version --verbose`, | |
66 | which includes important information about what platform you're on, what | |
67 | version of Rust you're using, etc. | |
68 | ||
69 | Sometimes, a backtrace is helpful, and so including that is nice. To get | |
70 | a backtrace, set the `RUST_BACKTRACE` environment variable. The easiest way | |
71 | to do this is to invoke `rustc` like this: | |
72 | ||
73 | ```bash | |
74 | $ RUST_BACKTRACE=1 rustc ... | |
1a4d82fc JJ |
75 | ``` |
76 | ||
85aaf69f | 77 | ## Pull Requests |
1a4d82fc | 78 | |
85aaf69f SL |
79 | Pull requests are the primary mechanism we use to change Rust. GitHub itself |
80 | has some [great documentation][pull-requests] on using the Pull Request | |
81 | feature. We use the 'fork and pull' model described there. | |
1a4d82fc | 82 | |
85aaf69f SL |
83 | [pull-requests]: https://help.github.com/articles/using-pull-requests/ |
84 | ||
85 | Please make pull requests against the `master` branch. | |
86 | ||
c1a9b12d SL |
87 | Compiling all of `make check` can take a while. When testing your pull request, |
88 | consider using one of the more specialized `make` targets to cut down on the | |
89 | amount of time you have to wait. You need to have built the compiler at least | |
90 | once before running these will work, but that’s only one full build rather than | |
91 | one each time. | |
92 | ||
93 | $ make -j8 rustc-stage1 && make check-stage1 | |
94 | ||
95 | is one such example, which builds just `rustc`, and then runs the tests. If | |
96 | you’re adding something to the standard library, try | |
97 | ||
98 | $ make -j8 check-stage1-std NO_REBUILD=1 | |
99 | ||
100 | This will not rebuild the compiler, but will run the tests. | |
101 | ||
85aaf69f | 102 | All pull requests are reviewed by another person. We have a bot, |
62682a34 SL |
103 | @rust-highfive, that will automatically assign a random person to review your |
104 | request. | |
85aaf69f SL |
105 | |
106 | If you want to request that a specific person reviews your pull request, | |
107 | you can add an `r?` to the message. For example, Steve usually reviews | |
108 | documentation changes. So if you were to make a documentation change, add | |
109 | ||
110 | r? @steveklabnik | |
111 | ||
112 | to the end of the message, and @rust-highfive will assign @steveklabnik instead | |
113 | of a random person. This is entirely optional. | |
114 | ||
115 | After someone has reviewed your pull request, they will leave an annotation | |
116 | on the pull request with an `r+`. It will look something like this: | |
117 | ||
118 | @bors: r+ 38fe8d2 | |
119 | ||
120 | This tells @bors, our lovable integration bot, that your pull request has | |
121 | been approved. The PR then enters the [merge queue][merge-queue], where @bors | |
122 | will run all the tests on every platform we support. If it all works out, | |
123 | @bors will merge your code into `master` and close the pull request. | |
124 | ||
125 | [merge-queue]: http://buildbot.rust-lang.org/homu/queue/rust | |
126 | ||
c1a9b12d SL |
127 | Speaking of tests, Rust has a comprehensive test suite. More information about |
128 | it can be found | |
129 | [here](https://github.com/rust-lang/rust-wiki-backup/blob/master/Note-testsuite.md). | |
130 | ||
85aaf69f SL |
131 | ## Writing Documentation |
132 | ||
133 | Documentation improvements are very welcome. The source of `doc.rust-lang.org` | |
134 | is located in `src/doc` in the tree, and standard API documentation is generated | |
135 | from the source code itself. | |
136 | ||
c1a9b12d SL |
137 | Documentation pull requests function in the same way as other pull requests, |
138 | though you may see a slightly different form of `r+`: | |
85aaf69f SL |
139 | |
140 | @bors: r+ 38fe8d2 rollup | |
141 | ||
142 | That additional `rollup` tells @bors that this change is eligible for a 'rollup'. | |
143 | To save @bors some work, and to get small changes through more quickly, when | |
144 | @bors attempts to merge a commit that's rollup-eligible, it will also merge | |
145 | the other rollup-eligible patches too, and they'll get tested and merged at | |
146 | the same time. | |
147 | ||
b039eaaf | 148 | To find documentation-related issues, sort by the [A-docs label][adocs]. |
62682a34 SL |
149 | |
150 | [adocs]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AA-docs | |
151 | ||
b039eaaf SL |
152 | In many cases, you don't need a full `make doc`. You can use `rustdoc` directly |
153 | to check small fixes. For example, `rustdoc src/doc/reference.md` will render | |
154 | reference to `doc/reference.html`. The CSS might be messed up, but you can | |
155 | verify that HTML is right. | |
156 | ||
85aaf69f SL |
157 | ## Issue Triage |
158 | ||
159 | Sometimes, an issue will stay open, even though the bug has been fixed. And | |
160 | sometimes, the original bug may go stale because something has changed in the | |
161 | meantime. | |
162 | ||
163 | It can be helpful to go through older bug reports and make sure that they are | |
164 | still valid. Load up an older issue, double check that it's still true, and | |
62682a34 SL |
165 | leave a comment letting us know if it is or is not. The [least recently |
166 | updated sort][lru] is good for finding issues like this. | |
167 | ||
168 | Contributors with sufficient permissions on the Rust repo can help by adding | |
169 | labels to triage issues: | |
170 | ||
171 | * Yellow, **A**-prefixed labels state which **area** of the project an issue | |
b039eaaf | 172 | relates to. |
62682a34 | 173 | |
b039eaaf | 174 | * Magenta, **B**-prefixed labels identify bugs which **belong** elsewhere. |
62682a34 SL |
175 | |
176 | * Green, **E**-prefixed labels explain the level of **experience** necessary | |
177 | to fix the issue. | |
178 | ||
179 | * Red, **I**-prefixed labels indicate the **importance** of the issue. The | |
180 | [I-nominated][inom] label indicates that an issue has been nominated for | |
b039eaaf | 181 | prioritizing at the next triage meeting. |
62682a34 SL |
182 | |
183 | * Orange, **P**-prefixed labels indicate a bug's **priority**. These labels | |
184 | are only assigned during triage meetings, and replace the [I-nominated][inom] | |
b039eaaf | 185 | label. |
62682a34 SL |
186 | |
187 | * Blue, **T**-prefixed bugs denote which **team** the issue belongs to. | |
188 | ||
189 | * Dark blue, **beta-** labels track changes which need to be backported into | |
b039eaaf SL |
190 | the beta branches. |
191 | ||
62682a34 | 192 | * The purple **metabug** label marks lists of bugs collected by other |
b039eaaf | 193 | categories. |
62682a34 | 194 | |
b039eaaf | 195 | If you're looking for somewhere to start, check out the [E-easy][eeasy] tag. |
85aaf69f | 196 | |
62682a34 SL |
197 | [inom]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AI-nominated |
198 | [eeasy]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AE-easy | |
85aaf69f SL |
199 | [lru]: https://github.com/rust-lang/rust/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-asc |
200 | ||
201 | ## Out-of-tree Contributions | |
202 | ||
203 | There are a number of other ways to contribute to Rust that don't deal with | |
204 | this repository. | |
205 | ||
206 | Answer questions in [#rust][pound-rust], or on [users.rust-lang.org][users], | |
207 | or on [StackOverflow][so]. | |
208 | ||
209 | Participate in the [RFC process](https://github.com/rust-lang/rfcs). | |
210 | ||
211 | Find a [requested community library][community-library], build it, and publish | |
212 | it to [Crates.io](http://crates.io). Easier said than done, but very, very | |
213 | valuable! | |
1a4d82fc | 214 | |
85aaf69f | 215 | [pound-rust]: http://chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust |
e9174d1e | 216 | [users]: https://users.rust-lang.org/ |
85aaf69f SL |
217 | [so]: http://stackoverflow.com/questions/tagged/rust |
218 | [community-library]: https://github.com/rust-lang/rfcs/labels/A-community-library | |
e9174d1e SL |
219 | |
220 | ## Helpful Links and Information | |
221 | ||
222 | For people new to Rust, and just starting to contribute, or even for | |
223 | more seasoned developers, some useful places to look for information | |
224 | are: | |
225 | ||
226 | * The [Rust Internals forum][rif], a place to ask questions and | |
227 | discuss Rust's internals | |
228 | * The [generated documentation for rust's compiler][gdfrustc] | |
b039eaaf | 229 | * The [rust reference][rr], even though it doesn't specifically talk about Rust's internals, it's a great resource nonetheless |
e9174d1e SL |
230 | * Although out of date, [Tom Lee's great blog article][tlgba] is very helpful |
231 | * [rustaceans.org][ro] is helpful, but mostly dedicated to IRC | |
232 | * The [Rust Compiler Testing Docs][rctd] | |
b039eaaf SL |
233 | * For @bors, [this cheat sheet][cheatsheet] is helpful (Remember to replace `@homu` with `@bors` in the commands that you use.) |
234 | * **Google!** ([search only in Rust Documentation][gsearchdocs] to find types, traits, etc. quickly) | |
e9174d1e SL |
235 | * Don't be afraid to ask! The Rust community is friendly and helpful. |
236 | ||
237 | [gdfrustc]: http://manishearth.github.io/rust-internals-docs/rustc/ | |
b039eaaf | 238 | [gsearchdocs]: https://www.google.de/search?q=site:doc.rust-lang.org+your+query+here |
e9174d1e SL |
239 | [rif]: http://internals.rust-lang.org |
240 | [rr]: https://doc.rust-lang.org/book/README.html | |
241 | [tlgba]: http://tomlee.co/2014/04/03/a-more-detailed-tour-of-the-rust-compiler/ | |
242 | [ro]: http://www.rustaceans.org/ | |
243 | [rctd]: ./COMPILER_TESTS.md | |
b039eaaf | 244 | [cheatsheet]: http://buildbot.rust-lang.org/homu/ |