]>
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) | |
7453a54e | 9 | * [The Build System](#the-build-system) |
85aaf69f SL |
10 | * [Pull Requests](#pull-requests) |
11 | * [Writing Documentation](#writing-documentation) | |
12 | * [Issue Triage](#issue-triage) | |
13 | * [Out-of-tree Contributions](#out-of-tree-contributions) | |
e9174d1e | 14 | * [Helpful Links and Information](#helpful-links-and-information) |
1a4d82fc | 15 | |
85aaf69f SL |
16 | If you have questions, please make a post on [internals.rust-lang.org][internals] or |
17 | hop on [#rust-internals][pound-rust-internals]. | |
1a4d82fc | 18 | |
c34b1796 | 19 | As a reminder, all contributors are expected to follow our [Code of Conduct][coc]. |
1a4d82fc | 20 | |
85aaf69f | 21 | [pound-rust-internals]: http://chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust-internals |
e9174d1e SL |
22 | [internals]: https://internals.rust-lang.org |
23 | [coc]: https://www.rust-lang.org/conduct.html | |
1a4d82fc | 24 | |
85aaf69f | 25 | ## Feature Requests |
1a4d82fc | 26 | |
85aaf69f SL |
27 | To request a change to the way that the Rust language works, please open an |
28 | issue in the [RFCs repository](https://github.com/rust-lang/rfcs/issues/new) | |
29 | rather than this one. New features and other significant language changes | |
30 | must go through the RFC process. | |
1a4d82fc | 31 | |
85aaf69f | 32 | ## Bug Reports |
1a4d82fc | 33 | |
85aaf69f SL |
34 | While bugs are unfortunate, they're a reality in software. We can't fix what we |
35 | don't know about, so please report liberally. If you're not sure if something | |
36 | is a bug or not, feel free to file a bug anyway. | |
1a4d82fc | 37 | |
92a42be0 SL |
38 | **If you believe reporting your bug publicly represents a security risk to Rust users, |
39 | please follow our [instructions for reporting security vulnerabilities](https://www.rust-lang.org/security.html)**. | |
40 | ||
85aaf69f SL |
41 | If you have the chance, before reporting a bug, please [search existing |
42 | issues](https://github.com/rust-lang/rust/search?q=&type=Issues&utf8=%E2%9C%93), | |
43 | as it's possible that someone else has already reported your error. This doesn't | |
44 | always work, and sometimes it's hard to know what to search for, so consider this | |
45 | extra credit. We won't mind if you accidentally file a duplicate report. | |
1a4d82fc | 46 | |
85aaf69f SL |
47 | Opening an issue is as easy as following [this |
48 | link](https://github.com/rust-lang/rust/issues/new) and filling out the fields. | |
49 | Here's a template that you can use to file a bug, though it's not necessary to | |
50 | use it exactly: | |
1a4d82fc | 51 | |
85aaf69f SL |
52 | <short summary of the bug> |
53 | ||
54 | I tried this code: | |
55 | ||
56 | <code sample that causes the bug> | |
57 | ||
58 | I expected to see this happen: <explanation> | |
59 | ||
60 | Instead, this happened: <explanation> | |
61 | ||
62 | ## Meta | |
63 | ||
64 | `rustc --version --verbose`: | |
65 | ||
66 | Backtrace: | |
67 | ||
68 | All three components are important: what you did, what you expected, what | |
69 | happened instead. Please include the output of `rustc --version --verbose`, | |
70 | which includes important information about what platform you're on, what | |
71 | version of Rust you're using, etc. | |
72 | ||
73 | Sometimes, a backtrace is helpful, and so including that is nice. To get | |
54a0048b SL |
74 | a backtrace, set the `RUST_BACKTRACE` environment variable to a value |
75 | other than `0`. The easiest way | |
85aaf69f SL |
76 | to do this is to invoke `rustc` like this: |
77 | ||
78 | ```bash | |
79 | $ RUST_BACKTRACE=1 rustc ... | |
1a4d82fc JJ |
80 | ``` |
81 | ||
7453a54e SL |
82 | ## The Build System |
83 | ||
84 | Rust's build system allows you to bootstrap the compiler, run tests & | |
85 | benchmarks, generate documentation, install a fresh build of Rust, and more. | |
86 | It's your best friend when working on Rust, allowing you to compile & test | |
87 | your contributions before submission. | |
88 | ||
476ff2be SL |
89 | The build system lives in [the `src/bootstrap` directory][bootstrap] in the |
90 | project root. Our build system is itself written in Rust and is based on Cargo | |
91 | to actually build all the compiler's crates. If you have questions on the build | |
92 | system internals, try asking in [`#rust-internals`][pound-rust-internals]. | |
7453a54e | 93 | |
476ff2be SL |
94 | [bootstrap]: https://github.com/rust-lang/rust/tree/master/src/bootstrap/ |
95 | ||
7453a54e SL |
96 | ### Configuration |
97 | ||
98 | Before you can start building the compiler you need to configure the build for | |
99 | your system. In most cases, that will just mean using the defaults provided | |
8bb4bdeb | 100 | for Rust. |
7453a54e | 101 | |
8bb4bdeb XL |
102 | To change configuration, you must copy the file `src/bootstrap/config.toml.example` |
103 | to `config.toml` in the directory from which you will be running the build, and | |
104 | change the settings provided. | |
105 | ||
106 | There are large number of options provided in this config file that will alter the | |
107 | configuration used in the build process. Some options to note: | |
7453a54e | 108 | |
8bb4bdeb XL |
109 | #### `[llvm]`: |
110 | - `ccache = true` - Use ccache when building llvm | |
7453a54e | 111 | |
8bb4bdeb XL |
112 | #### `[build]`: |
113 | - `compiler-docs = true` - Build compiler documentation | |
7453a54e | 114 | |
8bb4bdeb XL |
115 | #### `[rust]`: |
116 | - `debuginfo = true` - Build a compiler with debuginfo | |
117 | - `optimize = false` - Disable optimizations to speed up compilation of stage1 rust | |
118 | ||
119 | For more options, the `config.toml` file contains commented out defaults, with | |
120 | descriptions of what each option will do. | |
121 | ||
122 | Note: Previously the `./configure` script was used to configure this | |
123 | project. It can still be used, but it's recommended to use a `config.toml` | |
124 | file. If you still have a `config.mk` file in your directory - from | |
125 | `./configure` - you may need to delete it for `config.toml` to work. | |
7453a54e | 126 | |
476ff2be SL |
127 | ### Building |
128 | ||
8bb4bdeb XL |
129 | The build system uses the `x.py` script to control the build process. This script |
130 | is used to build, test, and document various parts of the compiler. You can | |
131 | execute it as: | |
476ff2be SL |
132 | |
133 | ```sh | |
134 | python x.py build | |
135 | ``` | |
136 | ||
137 | On some systems you can also use the shorter version: | |
138 | ||
139 | ```sh | |
140 | ./x.py build | |
141 | ``` | |
142 | ||
143 | To learn more about the driver and top-level targets, you can execute: | |
144 | ||
145 | ```sh | |
146 | python x.py --help | |
147 | ``` | |
148 | ||
149 | The general format for the driver script is: | |
150 | ||
151 | ```sh | |
152 | python x.py <command> [<directory>] | |
153 | ``` | |
154 | ||
155 | Some example commands are `build`, `test`, and `doc`. These will build, test, | |
156 | and document the specified directory. The second argument, `<directory>`, is | |
157 | optional and defaults to working over the entire compiler. If specified, | |
158 | however, only that specific directory will be built. For example: | |
159 | ||
160 | ```sh | |
161 | # build the entire compiler | |
162 | python x.py build | |
163 | ||
164 | # build all documentation | |
165 | python x.py doc | |
166 | ||
167 | # run all test suites | |
168 | python x.py test | |
169 | ||
170 | # build only the standard library | |
171 | python x.py build src/libstd | |
172 | ||
173 | # test only one particular test suite | |
174 | python x.py test src/test/rustdoc | |
175 | ||
176 | # build only the stage0 libcore library | |
177 | python x.py build src/libcore --stage 0 | |
178 | ``` | |
179 | ||
180 | You can explore the build system throught the various `--help` pages for each | |
181 | subcommand. For example to learn more about a command you can run: | |
182 | ||
183 | ``` | |
184 | python x.py build --help | |
185 | ``` | |
186 | ||
187 | To learn about all possible rules you can execute, run: | |
188 | ||
189 | ``` | |
190 | python x.py build --help --verbose | |
191 | ``` | |
192 | ||
8bb4bdeb XL |
193 | Note: Previously `./configure` and `make` were used to build this project. |
194 | They are still available, but `x.py` is the recommended build system. | |
195 | ||
476ff2be SL |
196 | ### Useful commands |
197 | ||
198 | Some common invocations of `x.py` are: | |
199 | ||
200 | - `x.py build --help` - show the help message and explain the subcommand | |
201 | - `x.py build src/libtest --stage 1` - build up to (and including) the first | |
202 | stage. For most cases we don't need to build the stage2 compiler, so we can | |
203 | save time by not building it. The stage1 compiler is a fully functioning | |
204 | compiler and (probably) will be enough to determine if your change works as | |
205 | expected. | |
206 | - `x.py build src/rustc --stage 1` - This will build just rustc, without libstd. | |
207 | This is the fastest way to recompile after you changed only rustc source code. | |
208 | Note however that the resulting rustc binary won't have a stdlib to link | |
209 | against by default. You can build libstd once with `x.py build src/libstd`, | |
8bb4bdeb | 210 | but it is only guaranteed to work if recompiled, so if there are any issues |
476ff2be SL |
211 | recompile it. |
212 | - `x.py test` - build the full compiler & run all tests (takes a while). This | |
7453a54e SL |
213 | is what gets run by the continuous integration system against your pull |
214 | request. You should run this before submitting to make sure your tests pass | |
215 | & everything builds in the correct manner. | |
476ff2be SL |
216 | - `x.py test src/libstd --stage 1` - test the standard library without |
217 | recompiling stage 2. | |
218 | - `x.py test src/test/run-pass --test-args TESTNAME` - Run a matching set of | |
219 | tests. | |
54a0048b SL |
220 | - `TESTNAME` should be a substring of the tests to match against e.g. it could |
221 | be the fully qualified test name, or just a part of it. | |
7453a54e SL |
222 | `TESTNAME=collections::hash::map::test_map::test_capacity_not_less_than_len` |
223 | or `TESTNAME=test_capacity_not_less_than_len`. | |
476ff2be SL |
224 | - `x.py test src/test/run-pass --stage 1 --test-args <substring-of-test-name>` - |
225 | Run a single rpass test with the stage1 compiler (this will be quicker than | |
226 | running the command above as we only build the stage1 compiler, not the entire | |
227 | thing). You can also leave off the directory argument to run all stage1 test | |
228 | types. | |
229 | - `x.py test src/libcore --stage 1` - Run stage1 tests in `libcore`. | |
230 | - `x.py test src/tools/tidy` - Check that the source code is in compliance with | |
231 | Rust's style guidelines. There is no official document describing Rust's full | |
232 | guidelines as of yet, but basic rules like 4 spaces for indentation and no | |
233 | more than 99 characters in a single line should be kept in mind when writing | |
234 | code. | |
7453a54e | 235 | |
85aaf69f | 236 | ## Pull Requests |
1a4d82fc | 237 | |
85aaf69f SL |
238 | Pull requests are the primary mechanism we use to change Rust. GitHub itself |
239 | has some [great documentation][pull-requests] on using the Pull Request | |
240 | feature. We use the 'fork and pull' model described there. | |
1a4d82fc | 241 | |
85aaf69f SL |
242 | [pull-requests]: https://help.github.com/articles/using-pull-requests/ |
243 | ||
244 | Please make pull requests against the `master` branch. | |
245 | ||
8bb4bdeb XL |
246 | Compiling all of `./x.py test` can take a while. When testing your pull request, |
247 | consider using one of the more specialized `./x.py` targets to cut down on the | |
c1a9b12d SL |
248 | amount of time you have to wait. You need to have built the compiler at least |
249 | once before running these will work, but that’s only one full build rather than | |
250 | one each time. | |
251 | ||
476ff2be | 252 | $ python x.py test --stage 1 |
c1a9b12d SL |
253 | |
254 | is one such example, which builds just `rustc`, and then runs the tests. If | |
255 | you’re adding something to the standard library, try | |
256 | ||
476ff2be | 257 | $ python x.py test src/libstd --stage 1 |
c1a9b12d | 258 | |
9e0c209e SL |
259 | Please make sure your pull request is in compliance with Rust's style |
260 | guidelines by running | |
261 | ||
476ff2be | 262 | $ python x.py test src/tools/tidy |
9e0c209e SL |
263 | |
264 | Make this check before every pull request (and every new commit in a pull | |
265 | request) ; you can add [git hooks](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks) | |
266 | before every push to make sure you never forget to make this check. | |
267 | ||
85aaf69f | 268 | All pull requests are reviewed by another person. We have a bot, |
62682a34 SL |
269 | @rust-highfive, that will automatically assign a random person to review your |
270 | request. | |
85aaf69f SL |
271 | |
272 | If you want to request that a specific person reviews your pull request, | |
273 | you can add an `r?` to the message. For example, Steve usually reviews | |
274 | documentation changes. So if you were to make a documentation change, add | |
275 | ||
276 | r? @steveklabnik | |
277 | ||
278 | to the end of the message, and @rust-highfive will assign @steveklabnik instead | |
279 | of a random person. This is entirely optional. | |
280 | ||
281 | After someone has reviewed your pull request, they will leave an annotation | |
282 | on the pull request with an `r+`. It will look something like this: | |
283 | ||
284 | @bors: r+ 38fe8d2 | |
285 | ||
286 | This tells @bors, our lovable integration bot, that your pull request has | |
287 | been approved. The PR then enters the [merge queue][merge-queue], where @bors | |
288 | will run all the tests on every platform we support. If it all works out, | |
289 | @bors will merge your code into `master` and close the pull request. | |
290 | ||
476ff2be | 291 | [merge-queue]: https://buildbot.rust-lang.org/homu/queue/rust |
85aaf69f | 292 | |
c1a9b12d SL |
293 | Speaking of tests, Rust has a comprehensive test suite. More information about |
294 | it can be found | |
295 | [here](https://github.com/rust-lang/rust-wiki-backup/blob/master/Note-testsuite.md). | |
296 | ||
85aaf69f SL |
297 | ## Writing Documentation |
298 | ||
299 | Documentation improvements are very welcome. The source of `doc.rust-lang.org` | |
300 | is located in `src/doc` in the tree, and standard API documentation is generated | |
301 | from the source code itself. | |
302 | ||
c1a9b12d SL |
303 | Documentation pull requests function in the same way as other pull requests, |
304 | though you may see a slightly different form of `r+`: | |
85aaf69f SL |
305 | |
306 | @bors: r+ 38fe8d2 rollup | |
307 | ||
308 | That additional `rollup` tells @bors that this change is eligible for a 'rollup'. | |
309 | To save @bors some work, and to get small changes through more quickly, when | |
310 | @bors attempts to merge a commit that's rollup-eligible, it will also merge | |
311 | the other rollup-eligible patches too, and they'll get tested and merged at | |
312 | the same time. | |
313 | ||
cc61c64b | 314 | To find documentation-related issues, sort by the [T-doc label][tdoc]. |
62682a34 | 315 | |
cc61c64b XL |
316 | [tdoc]: https://github.com/rust-lang/rust/issues?q=is%3Aopen%20is%3Aissue%20label%3AT-doc |
317 | ||
318 | You can find documentation style guidelines in [RFC 1574][rfc1574]. | |
319 | ||
320 | [rfc1574]: https://github.com/rust-lang/rfcs/blob/master/text/1574-more-api-documentation-conventions.md#appendix-a-full-conventions-text | |
62682a34 | 321 | |
8bb4bdeb | 322 | In many cases, you don't need a full `./x.py doc`. You can use `rustdoc` directly |
b039eaaf SL |
323 | to check small fixes. For example, `rustdoc src/doc/reference.md` will render |
324 | reference to `doc/reference.html`. The CSS might be messed up, but you can | |
9e0c209e | 325 | verify that the HTML is right. |
b039eaaf | 326 | |
85aaf69f SL |
327 | ## Issue Triage |
328 | ||
329 | Sometimes, an issue will stay open, even though the bug has been fixed. And | |
330 | sometimes, the original bug may go stale because something has changed in the | |
331 | meantime. | |
332 | ||
333 | It can be helpful to go through older bug reports and make sure that they are | |
334 | still valid. Load up an older issue, double check that it's still true, and | |
62682a34 SL |
335 | leave a comment letting us know if it is or is not. The [least recently |
336 | updated sort][lru] is good for finding issues like this. | |
337 | ||
338 | Contributors with sufficient permissions on the Rust repo can help by adding | |
339 | labels to triage issues: | |
340 | ||
341 | * Yellow, **A**-prefixed labels state which **area** of the project an issue | |
b039eaaf | 342 | relates to. |
62682a34 | 343 | |
9cc50fc6 | 344 | * Magenta, **B**-prefixed labels identify bugs which are **blockers**. |
62682a34 SL |
345 | |
346 | * Green, **E**-prefixed labels explain the level of **experience** necessary | |
347 | to fix the issue. | |
348 | ||
349 | * Red, **I**-prefixed labels indicate the **importance** of the issue. The | |
350 | [I-nominated][inom] label indicates that an issue has been nominated for | |
b039eaaf | 351 | prioritizing at the next triage meeting. |
62682a34 SL |
352 | |
353 | * Orange, **P**-prefixed labels indicate a bug's **priority**. These labels | |
354 | are only assigned during triage meetings, and replace the [I-nominated][inom] | |
b039eaaf | 355 | label. |
62682a34 SL |
356 | |
357 | * Blue, **T**-prefixed bugs denote which **team** the issue belongs to. | |
358 | ||
359 | * Dark blue, **beta-** labels track changes which need to be backported into | |
b039eaaf SL |
360 | the beta branches. |
361 | ||
62682a34 | 362 | * The purple **metabug** label marks lists of bugs collected by other |
b039eaaf | 363 | categories. |
62682a34 | 364 | |
b039eaaf | 365 | If you're looking for somewhere to start, check out the [E-easy][eeasy] tag. |
85aaf69f | 366 | |
62682a34 SL |
367 | [inom]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AI-nominated |
368 | [eeasy]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AE-easy | |
85aaf69f SL |
369 | [lru]: https://github.com/rust-lang/rust/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-asc |
370 | ||
371 | ## Out-of-tree Contributions | |
372 | ||
373 | There are a number of other ways to contribute to Rust that don't deal with | |
374 | this repository. | |
375 | ||
376 | Answer questions in [#rust][pound-rust], or on [users.rust-lang.org][users], | |
377 | or on [StackOverflow][so]. | |
378 | ||
379 | Participate in the [RFC process](https://github.com/rust-lang/rfcs). | |
380 | ||
381 | Find a [requested community library][community-library], build it, and publish | |
382 | it to [Crates.io](http://crates.io). Easier said than done, but very, very | |
383 | valuable! | |
1a4d82fc | 384 | |
85aaf69f | 385 | [pound-rust]: http://chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust |
e9174d1e | 386 | [users]: https://users.rust-lang.org/ |
85aaf69f SL |
387 | [so]: http://stackoverflow.com/questions/tagged/rust |
388 | [community-library]: https://github.com/rust-lang/rfcs/labels/A-community-library | |
e9174d1e SL |
389 | |
390 | ## Helpful Links and Information | |
391 | ||
392 | For people new to Rust, and just starting to contribute, or even for | |
393 | more seasoned developers, some useful places to look for information | |
394 | are: | |
395 | ||
396 | * The [Rust Internals forum][rif], a place to ask questions and | |
397 | discuss Rust's internals | |
398 | * The [generated documentation for rust's compiler][gdfrustc] | |
b039eaaf | 399 | * The [rust reference][rr], even though it doesn't specifically talk about Rust's internals, it's a great resource nonetheless |
e9174d1e SL |
400 | * Although out of date, [Tom Lee's great blog article][tlgba] is very helpful |
401 | * [rustaceans.org][ro] is helpful, but mostly dedicated to IRC | |
402 | * The [Rust Compiler Testing Docs][rctd] | |
b039eaaf SL |
403 | * For @bors, [this cheat sheet][cheatsheet] is helpful (Remember to replace `@homu` with `@bors` in the commands that you use.) |
404 | * **Google!** ([search only in Rust Documentation][gsearchdocs] to find types, traits, etc. quickly) | |
e9174d1e SL |
405 | * Don't be afraid to ask! The Rust community is friendly and helpful. |
406 | ||
407 | [gdfrustc]: http://manishearth.github.io/rust-internals-docs/rustc/ | |
9cc50fc6 | 408 | [gsearchdocs]: https://www.google.com/search?q=site:doc.rust-lang.org+your+query+here |
e9174d1e SL |
409 | [rif]: http://internals.rust-lang.org |
410 | [rr]: https://doc.rust-lang.org/book/README.html | |
a7813a04 | 411 | [tlgba]: http://tomlee.co/2014/04/a-more-detailed-tour-of-the-rust-compiler/ |
e9174d1e | 412 | [ro]: http://www.rustaceans.org/ |
8bb4bdeb | 413 | [rctd]: ./src/test/COMPILER_TESTS.md |
476ff2be | 414 | [cheatsheet]: https://buildbot.rust-lang.org/homu/ |