]>
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 | ||
89 | All the configuration for the build system lives in [the `mk` directory][mkdir] | |
90 | in the project root. It can be hard to follow in places, as it uses some | |
91 | advanced Make features which make for some challenging reading. If you have | |
92 | questions on the build system internals, try asking in | |
93 | [`#rust-internals`][pound-rust-internals]. | |
94 | ||
95 | [mkdir]: https://github.com/rust-lang/rust/tree/master/mk/ | |
96 | ||
97 | ### Configuration | |
98 | ||
99 | Before you can start building the compiler you need to configure the build for | |
100 | your system. In most cases, that will just mean using the defaults provided | |
101 | for Rust. Configuring involves invoking the `configure` script in the project | |
102 | root. | |
103 | ||
104 | ``` | |
105 | ./configure | |
106 | ``` | |
107 | ||
108 | There are large number of options accepted by this script to alter the | |
109 | configuration used later in the build process. Some options to note: | |
110 | ||
3157f602 XL |
111 | - `--enable-debug` - Build a debug version of the compiler (disables optimizations, |
112 | which speeds up compilation of stage1 rustc) | |
7453a54e SL |
113 | - `--enable-optimize` - Enable optimizations (can be used with `--enable-debug` |
114 | to make a debug build with optimizations) | |
115 | - `--disable-valgrind-rpass` - Don't run tests with valgrind | |
116 | - `--enable-clang` - Prefer clang to gcc for building dependencies (e.g., LLVM) | |
117 | - `--enable-ccache` - Invoke clang/gcc with ccache to re-use object files between builds | |
118 | - `--enable-compiler-docs` - Build compiler documentation | |
119 | ||
120 | To see a full list of options, run `./configure --help`. | |
121 | ||
122 | ### Useful Targets | |
123 | ||
124 | Some common make targets are: | |
125 | ||
3157f602 XL |
126 | - `make tips` - show useful targets, variables and other tips for working with |
127 | the build system. | |
7453a54e SL |
128 | - `make rustc-stage1` - build up to (and including) the first stage. For most |
129 | cases we don't need to build the stage2 compiler, so we can save time by not | |
130 | building it. The stage1 compiler is a fully functioning compiler and | |
131 | (probably) will be enough to determine if your change works as expected. | |
3157f602 XL |
132 | - `make $host/stage1/bin/rustc` - Where $host is a target triple like x86_64-unknown-linux-gnu. |
133 | This will build just rustc, without libstd. This is the fastest way to recompile after | |
134 | you changed only rustc source code. Note however that the resulting rustc binary | |
135 | won't have a stdlib to link against by default. You can build libstd once with | |
136 | `make rustc-stage1`, rustc will pick it up afterwards. libstd is only guaranteed to | |
137 | work if recompiled, so if there are any issues recompile it. | |
7453a54e SL |
138 | - `make check` - build the full compiler & run all tests (takes a while). This |
139 | is what gets run by the continuous integration system against your pull | |
140 | request. You should run this before submitting to make sure your tests pass | |
141 | & everything builds in the correct manner. | |
142 | - `make check-stage1-std NO_REBUILD=1` - test the standard library without | |
143 | rebuilding the entire compiler | |
144 | - `make check TESTNAME=<substring-of-test-name>` - Run a matching set of tests. | |
54a0048b SL |
145 | - `TESTNAME` should be a substring of the tests to match against e.g. it could |
146 | be the fully qualified test name, or just a part of it. | |
7453a54e SL |
147 | `TESTNAME=collections::hash::map::test_map::test_capacity_not_less_than_len` |
148 | or `TESTNAME=test_capacity_not_less_than_len`. | |
149 | - `make check-stage1-rpass TESTNAME=<substring-of-test-name>` - Run a single | |
150 | rpass test with the stage1 compiler (this will be quicker than running the | |
151 | command above as we only build the stage1 compiler, not the entire thing). | |
152 | You can also leave off the `-rpass` to run all stage1 test types. | |
153 | - `make check-stage1-coretest` - Run stage1 tests in `libcore`. | |
9e0c209e SL |
154 | - `make tidy` - Check that the source code is in compliance with Rust's style |
155 | guidelines. There is no official document describing Rust's full guidelines | |
156 | as of yet, but basic rules like 4 spaces for indentation and no more than 99 | |
157 | characters in a single line should be kept in mind when writing code. | |
7453a54e | 158 | |
85aaf69f | 159 | ## Pull Requests |
1a4d82fc | 160 | |
85aaf69f SL |
161 | Pull requests are the primary mechanism we use to change Rust. GitHub itself |
162 | has some [great documentation][pull-requests] on using the Pull Request | |
163 | feature. We use the 'fork and pull' model described there. | |
1a4d82fc | 164 | |
85aaf69f SL |
165 | [pull-requests]: https://help.github.com/articles/using-pull-requests/ |
166 | ||
167 | Please make pull requests against the `master` branch. | |
168 | ||
c1a9b12d SL |
169 | Compiling all of `make check` can take a while. When testing your pull request, |
170 | consider using one of the more specialized `make` targets to cut down on the | |
171 | amount of time you have to wait. You need to have built the compiler at least | |
172 | once before running these will work, but that’s only one full build rather than | |
173 | one each time. | |
174 | ||
175 | $ make -j8 rustc-stage1 && make check-stage1 | |
176 | ||
177 | is one such example, which builds just `rustc`, and then runs the tests. If | |
178 | you’re adding something to the standard library, try | |
179 | ||
180 | $ make -j8 check-stage1-std NO_REBUILD=1 | |
181 | ||
182 | This will not rebuild the compiler, but will run the tests. | |
183 | ||
9e0c209e SL |
184 | Please make sure your pull request is in compliance with Rust's style |
185 | guidelines by running | |
186 | ||
187 | $ make tidy | |
188 | ||
189 | Make this check before every pull request (and every new commit in a pull | |
190 | request) ; you can add [git hooks](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks) | |
191 | before every push to make sure you never forget to make this check. | |
192 | ||
85aaf69f | 193 | All pull requests are reviewed by another person. We have a bot, |
62682a34 SL |
194 | @rust-highfive, that will automatically assign a random person to review your |
195 | request. | |
85aaf69f SL |
196 | |
197 | If you want to request that a specific person reviews your pull request, | |
198 | you can add an `r?` to the message. For example, Steve usually reviews | |
199 | documentation changes. So if you were to make a documentation change, add | |
200 | ||
201 | r? @steveklabnik | |
202 | ||
203 | to the end of the message, and @rust-highfive will assign @steveklabnik instead | |
204 | of a random person. This is entirely optional. | |
205 | ||
206 | After someone has reviewed your pull request, they will leave an annotation | |
207 | on the pull request with an `r+`. It will look something like this: | |
208 | ||
209 | @bors: r+ 38fe8d2 | |
210 | ||
211 | This tells @bors, our lovable integration bot, that your pull request has | |
212 | been approved. The PR then enters the [merge queue][merge-queue], where @bors | |
213 | will run all the tests on every platform we support. If it all works out, | |
214 | @bors will merge your code into `master` and close the pull request. | |
215 | ||
216 | [merge-queue]: http://buildbot.rust-lang.org/homu/queue/rust | |
217 | ||
c1a9b12d SL |
218 | Speaking of tests, Rust has a comprehensive test suite. More information about |
219 | it can be found | |
220 | [here](https://github.com/rust-lang/rust-wiki-backup/blob/master/Note-testsuite.md). | |
221 | ||
85aaf69f SL |
222 | ## Writing Documentation |
223 | ||
224 | Documentation improvements are very welcome. The source of `doc.rust-lang.org` | |
225 | is located in `src/doc` in the tree, and standard API documentation is generated | |
226 | from the source code itself. | |
227 | ||
c1a9b12d SL |
228 | Documentation pull requests function in the same way as other pull requests, |
229 | though you may see a slightly different form of `r+`: | |
85aaf69f SL |
230 | |
231 | @bors: r+ 38fe8d2 rollup | |
232 | ||
233 | That additional `rollup` tells @bors that this change is eligible for a 'rollup'. | |
234 | To save @bors some work, and to get small changes through more quickly, when | |
235 | @bors attempts to merge a commit that's rollup-eligible, it will also merge | |
236 | the other rollup-eligible patches too, and they'll get tested and merged at | |
237 | the same time. | |
238 | ||
b039eaaf | 239 | To find documentation-related issues, sort by the [A-docs label][adocs]. |
62682a34 SL |
240 | |
241 | [adocs]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AA-docs | |
242 | ||
b039eaaf SL |
243 | In many cases, you don't need a full `make doc`. You can use `rustdoc` directly |
244 | to check small fixes. For example, `rustdoc src/doc/reference.md` will render | |
245 | reference to `doc/reference.html`. The CSS might be messed up, but you can | |
9e0c209e | 246 | verify that the HTML is right. |
b039eaaf | 247 | |
85aaf69f SL |
248 | ## Issue Triage |
249 | ||
250 | Sometimes, an issue will stay open, even though the bug has been fixed. And | |
251 | sometimes, the original bug may go stale because something has changed in the | |
252 | meantime. | |
253 | ||
254 | It can be helpful to go through older bug reports and make sure that they are | |
255 | still valid. Load up an older issue, double check that it's still true, and | |
62682a34 SL |
256 | leave a comment letting us know if it is or is not. The [least recently |
257 | updated sort][lru] is good for finding issues like this. | |
258 | ||
259 | Contributors with sufficient permissions on the Rust repo can help by adding | |
260 | labels to triage issues: | |
261 | ||
262 | * Yellow, **A**-prefixed labels state which **area** of the project an issue | |
b039eaaf | 263 | relates to. |
62682a34 | 264 | |
9cc50fc6 | 265 | * Magenta, **B**-prefixed labels identify bugs which are **blockers**. |
62682a34 SL |
266 | |
267 | * Green, **E**-prefixed labels explain the level of **experience** necessary | |
268 | to fix the issue. | |
269 | ||
270 | * Red, **I**-prefixed labels indicate the **importance** of the issue. The | |
271 | [I-nominated][inom] label indicates that an issue has been nominated for | |
b039eaaf | 272 | prioritizing at the next triage meeting. |
62682a34 SL |
273 | |
274 | * Orange, **P**-prefixed labels indicate a bug's **priority**. These labels | |
275 | are only assigned during triage meetings, and replace the [I-nominated][inom] | |
b039eaaf | 276 | label. |
62682a34 SL |
277 | |
278 | * Blue, **T**-prefixed bugs denote which **team** the issue belongs to. | |
279 | ||
280 | * Dark blue, **beta-** labels track changes which need to be backported into | |
b039eaaf SL |
281 | the beta branches. |
282 | ||
62682a34 | 283 | * The purple **metabug** label marks lists of bugs collected by other |
b039eaaf | 284 | categories. |
62682a34 | 285 | |
b039eaaf | 286 | If you're looking for somewhere to start, check out the [E-easy][eeasy] tag. |
85aaf69f | 287 | |
62682a34 SL |
288 | [inom]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AI-nominated |
289 | [eeasy]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AE-easy | |
85aaf69f SL |
290 | [lru]: https://github.com/rust-lang/rust/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-asc |
291 | ||
292 | ## Out-of-tree Contributions | |
293 | ||
294 | There are a number of other ways to contribute to Rust that don't deal with | |
295 | this repository. | |
296 | ||
297 | Answer questions in [#rust][pound-rust], or on [users.rust-lang.org][users], | |
298 | or on [StackOverflow][so]. | |
299 | ||
300 | Participate in the [RFC process](https://github.com/rust-lang/rfcs). | |
301 | ||
302 | Find a [requested community library][community-library], build it, and publish | |
303 | it to [Crates.io](http://crates.io). Easier said than done, but very, very | |
304 | valuable! | |
1a4d82fc | 305 | |
85aaf69f | 306 | [pound-rust]: http://chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust |
e9174d1e | 307 | [users]: https://users.rust-lang.org/ |
85aaf69f SL |
308 | [so]: http://stackoverflow.com/questions/tagged/rust |
309 | [community-library]: https://github.com/rust-lang/rfcs/labels/A-community-library | |
e9174d1e SL |
310 | |
311 | ## Helpful Links and Information | |
312 | ||
313 | For people new to Rust, and just starting to contribute, or even for | |
314 | more seasoned developers, some useful places to look for information | |
315 | are: | |
316 | ||
317 | * The [Rust Internals forum][rif], a place to ask questions and | |
318 | discuss Rust's internals | |
319 | * The [generated documentation for rust's compiler][gdfrustc] | |
b039eaaf | 320 | * The [rust reference][rr], even though it doesn't specifically talk about Rust's internals, it's a great resource nonetheless |
e9174d1e SL |
321 | * Although out of date, [Tom Lee's great blog article][tlgba] is very helpful |
322 | * [rustaceans.org][ro] is helpful, but mostly dedicated to IRC | |
323 | * The [Rust Compiler Testing Docs][rctd] | |
b039eaaf SL |
324 | * For @bors, [this cheat sheet][cheatsheet] is helpful (Remember to replace `@homu` with `@bors` in the commands that you use.) |
325 | * **Google!** ([search only in Rust Documentation][gsearchdocs] to find types, traits, etc. quickly) | |
e9174d1e SL |
326 | * Don't be afraid to ask! The Rust community is friendly and helpful. |
327 | ||
328 | [gdfrustc]: http://manishearth.github.io/rust-internals-docs/rustc/ | |
9cc50fc6 | 329 | [gsearchdocs]: https://www.google.com/search?q=site:doc.rust-lang.org+your+query+here |
e9174d1e SL |
330 | [rif]: http://internals.rust-lang.org |
331 | [rr]: https://doc.rust-lang.org/book/README.html | |
a7813a04 | 332 | [tlgba]: http://tomlee.co/2014/04/a-more-detailed-tour-of-the-rust-compiler/ |
e9174d1e SL |
333 | [ro]: http://www.rustaceans.org/ |
334 | [rctd]: ./COMPILER_TESTS.md | |
b039eaaf | 335 | [cheatsheet]: http://buildbot.rust-lang.org/homu/ |