|
1 | | -## How to submit a bug report |
| 1 | +# Contributing to Rust |
2 | 2 |
|
3 | | -If you're just reporting a bug, please see: |
| 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: |
4 | 6 |
|
5 | | -http://doc.rust-lang.org/complement-bugreport.html |
| 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) |
6 | 13 |
|
7 | | -## Submitting an issue |
| 14 | +If you have questions, please make a post on [internals.rust-lang.org][internals] or |
| 15 | +hop on [#rust-internals][pound-rust-internals]. |
8 | 16 |
|
9 | | -Please submit issues here for bug reports or implementation details. For feature |
10 | | -requests, language changes, or major changes to the libraries, please submit an |
11 | | -issue against the [RFCs repository](https://github.com/rust-lang/rfcs). |
| 17 | +As a reminder, all contributors are expected to follow our [Code of Conduct](coc). |
12 | 18 |
|
13 | | -## Pull request procedure |
| 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 |
14 | 22 |
|
15 | | -Pull requests should be targeted at Rust's `master` branch. |
16 | | -Before pushing to your Github repo and issuing the pull request, |
17 | | -please do two things: |
| 23 | +## Feature Requests |
18 | 24 |
|
19 | | -1. [Rebase](http://git-scm.com/book/en/Git-Branching-Rebasing) your |
20 | | - local changes against the `master` branch. Resolve any conflicts |
21 | | - that arise. |
| 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. |
22 | 29 |
|
23 | | -2. Run the full Rust test suite with the `make check` command. You're |
24 | | - not off the hook even if you just stick to documentation; code |
25 | | - examples in the docs are tested as well! Although for simple |
26 | | - wording or grammar fixes, this is probably unnecessary. |
| 30 | +## Bug Reports |
27 | 31 |
|
28 | | -Pull requests will be treated as "review requests", and we will give |
29 | | -feedback we expect to see corrected on |
30 | | -[style](http://aturon.github.io/) and |
31 | | -substance before pulling. Changes contributed via pull request should |
32 | | -focus on a single issue at a time, like any other. We will not accept |
33 | | -pull-requests that try to "sneak" unrelated changes in. |
| 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. |
34 | 35 |
|
35 | | -Normally, all pull requests must include regression tests (see |
36 | | -[Note-testsuite](https://github.com/rust-lang/rust/wiki/Note-testsuite)) |
37 | | -that test your change. Occasionally, a change will be very difficult |
38 | | -to test for. In those cases, please include a note in your commit |
39 | | -message explaining why. |
| 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. |
40 | 41 |
|
41 | | -In the licensing header at the beginning of any files you change, |
42 | | -please make sure the listed date range includes the current year. For |
43 | | -example, if it's 2014, and you change a Rust file that was created in |
44 | | -2010, it should begin: |
| 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: |
45 | 46 |
|
46 | | -``` |
47 | | -// Copyright 2010-2014 The Rust Project Developers. |
| 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 ... |
48 | 74 | ``` |
49 | 75 |
|
50 | | -# Coordination and communication |
| 76 | +## Pull Requests |
51 | 77 |
|
52 | | -Get feedback from other developers on |
53 | | -[internals.rust-lang.org][internals], and |
54 | | -[#rust-internals][pound-rust-internals]. |
| 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. |
55 | 81 |
|
56 | | -[pound-rust-internals]: http://chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust-internals |
57 | | -[internals]: http://internals.rust-lang.org |
| 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, |
| 87 | +@rust-highfive, that will automatically assign a random person to review your request. |
| 88 | + |
| 89 | +If you want to request that a specific person reviews your pull request, |
| 90 | +you can add an `r?` to the message. For example, Steve usually reviews |
| 91 | +documentation changes. So if you were to make a documentation change, add |
| 92 | + |
| 93 | + r? @steveklabnik |
| 94 | + |
| 95 | +to the end of the message, and @rust-highfive will assign @steveklabnik instead |
| 96 | +of a random person. This is entirely optional. |
| 97 | + |
| 98 | +After someone has reviewed your pull request, they will leave an annotation |
| 99 | +on the pull request with an `r+`. It will look something like this: |
| 100 | + |
| 101 | + @bors: r+ 38fe8d2 |
| 102 | + |
| 103 | +This tells @bors, our lovable integration bot, that your pull request has |
| 104 | +been approved. The PR then enters the [merge queue][merge-queue], where @bors |
| 105 | +will run all the tests on every platform we support. If it all works out, |
| 106 | +@bors will merge your code into `master` and close the pull request. |
| 107 | + |
| 108 | +[merge-queue]: http://buildbot.rust-lang.org/homu/queue/rust |
| 109 | + |
| 110 | +## Writing Documentation |
| 111 | + |
| 112 | +Documentation improvements are very welcome. The source of `doc.rust-lang.org` |
| 113 | +is located in `src/doc` in the tree, and standard API documentation is generated |
| 114 | +from the source code itself. |
| 115 | + |
| 116 | +Documentation pull requests function in the same as other pull requests, though |
| 117 | +you may see a slightly different form of `r+`: |
| 118 | + |
| 119 | + @bors: r+ 38fe8d2 rollup |
| 120 | + |
| 121 | +That additional `rollup` tells @bors that this change is eligible for a 'rollup'. |
| 122 | +To save @bors some work, and to get small changes through more quickly, when |
| 123 | +@bors attempts to merge a commit that's rollup-eligible, it will also merge |
| 124 | +the other rollup-eligible patches too, and they'll get tested and merged at |
| 125 | +the same time. |
| 126 | + |
| 127 | +## Issue Triage |
| 128 | + |
| 129 | +Sometimes, an issue will stay open, even though the bug has been fixed. And |
| 130 | +sometimes, the original bug may go stale because something has changed in the |
| 131 | +meantime. |
| 132 | + |
| 133 | +It can be helpful to go through older bug reports and make sure that they are |
| 134 | +still valid. Load up an older issue, double check that it's still true, and |
| 135 | +leave a comment letting us know if it is or is not. The [least recently updated sort][lru] is good for finding issues like this. |
| 136 | + |
| 137 | +[lru]: https://github.com/rust-lang/rust/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-asc |
| 138 | + |
| 139 | +## Out-of-tree Contributions |
| 140 | + |
| 141 | +There are a number of other ways to contribute to Rust that don't deal with |
| 142 | +this repository. |
| 143 | + |
| 144 | +Answer questions in [#rust][pound-rust], or on [users.rust-lang.org][users], |
| 145 | +or on [StackOverflow][so]. |
| 146 | + |
| 147 | +Participate in the [RFC process](https://github.com/rust-lang/rfcs). |
| 148 | + |
| 149 | +Find a [requested community library][community-library], build it, and publish |
| 150 | +it to [Crates.io](http://crates.io). Easier said than done, but very, very |
| 151 | +valuable! |
58 | 152 |
|
59 | | -For more details, please refer to |
60 | | -[Note-development-policy](https://github.com/rust-lang/rust/wiki/Note-development-policy). |
| 153 | +[pound-rust]: http://chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust |
| 154 | +[users]: http://users.rust-lang.org/ |
| 155 | +[so]: http://stackoverflow.com/questions/tagged/rust |
| 156 | +[community-library]: https://github.com/rust-lang/rfcs/labels/A-community-library |
0 commit comments