|
1 | | -# Contributing to Rust |
| 1 | +## How to submit a bug report |
2 | 2 |
|
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: |
| 3 | +If you're just reporting a bug, please see: |
6 | 4 |
|
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) |
| 5 | +http://doc.rust-lang.org/complement-bugreport.html |
13 | 6 |
|
14 | | -If you have questions, please make a post on [internals.rust-lang.org][internals] or |
15 | | -hop on [#rust-internals][pound-rust-internals]. |
| 7 | +## Submitting an issue |
16 | 8 |
|
17 | | -As a reminder, all contributors are expected to follow our [Code of Conduct](coc). |
| 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). |
18 | 12 |
|
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 |
22 | | - |
23 | | -## Feature Requests |
24 | | - |
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. |
29 | | - |
30 | | -## Bug Reports |
31 | | - |
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. |
35 | | - |
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. |
41 | | - |
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: |
46 | | - |
47 | | - <short summary of the bug> |
48 | | - |
49 | | - I tried this code: |
| 13 | +## Pull request procedure |
50 | 14 |
|
51 | | - <code sample that causes the bug> |
| 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: |
52 | 18 |
|
53 | | - I expected to see this happen: <explanation> |
| 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. |
54 | 22 |
|
55 | | - Instead, this happened: <explanation> |
| 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. |
56 | 27 |
|
57 | | - ## Meta |
| 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. |
58 | 34 |
|
59 | | - `rustc --version --verbose`: |
| 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. |
60 | 40 |
|
61 | | - Backtrace: |
| 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: |
62 | 45 |
|
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 ... |
| 46 | +``` |
| 47 | +// Copyright 2010-2014 The Rust Project Developers. |
74 | 48 | ``` |
75 | 49 |
|
76 | | -## Pull Requests |
77 | | - |
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. |
81 | | - |
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]. |
| 50 | +# Coordination and communication |
146 | 51 |
|
147 | | -Participate in the [RFC process](https://github.com/rust-lang/rfcs). |
| 52 | +Get feedback from other developers on |
| 53 | +[internals.rust-lang.org][internals], and |
| 54 | +[#rust-internals][pound-rust-internals]. |
148 | 55 |
|
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! |
| 56 | +[pound-rust-internals]: http://chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust-internals |
| 57 | +[internals]: http://internals.rust-lang.org |
152 | 58 |
|
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 |
| 59 | +For more details, please refer to |
| 60 | +[Note-development-policy](https://github.com/rust-lang/rust/wiki/Note-development-policy). |
0 commit comments