CONTRIBUTING.md

   1 # Contributing to Rust
   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:
   6
   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)
  13
  14 If you have questions, please make a post on [internals.rust-lang.org][internals] or
  15 hop on [#rust-internals][pound-rust-internals].
  16
  17 As a reminder, all contributors are expected to follow our [Code of Conduct][coc].
  18
  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:
  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 ...
  74 ```
  75
  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 Compiling all of `make check` can take a while. When testing your pull request,
  87 consider using one of the more specialized `make` targets to cut down on the
  88 amount of time you have to wait. You need to have built the compiler at least
  89 once before running these will work, but that’s only one full build rather than
  90 one each time.
  91
  92     $ make -j8 rustc-stage1 && make check-stage1
  93
  94 is one such example, which builds just `rustc`, and then runs the tests. If
  95 you’re adding something to the standard library, try
  96
  97     $ make -j8 check-stage1-std NO_REBUILD=1
  98
  99 This will not rebuild the compiler, but will run the tests.
 100
 101 All pull requests are reviewed by another person. We have a bot,
 102 @rust-highfive, that will automatically assign a random person to review your
 103 request.
 104
 105 If you want to request that a specific person reviews your pull request,
 106 you can add an `r?` to the message. For example, Steve usually reviews
 107 documentation changes. So if you were to make a documentation change, add
 108
 109     r? @steveklabnik
 110
 111 to the end of the message, and @rust-highfive will assign @steveklabnik instead
 112 of a random person. This is entirely optional.
 113
 114 After someone has reviewed your pull request, they will leave an annotation
 115 on the pull request with an `r+`. It will look something like this:
 116
 117     @bors: r+ 38fe8d2
 118
 119 This tells @bors, our lovable integration bot, that your pull request has
 120 been approved. The PR then enters the [merge queue][merge-queue], where @bors
 121 will run all the tests on every platform we support. If it all works out,
 122 @bors will merge your code into `master` and close the pull request.
 123
 124 [merge-queue]: http://buildbot.rust-lang.org/homu/queue/rust
 125
 126 Speaking of tests, Rust has a comprehensive test suite. More information about
 127 it can be found
 128 [here](https://github.com/rust-lang/rust-wiki-backup/blob/master/Note-testsuite.md).
 129
 130 ## Writing Documentation
 131
 132 Documentation improvements are very welcome. The source of `doc.rust-lang.org`
 133 is located in `src/doc` in the tree, and standard API documentation is generated
 134 from the source code itself.
 135
 136 Documentation pull requests function in the same way as other pull requests,
 137 though you may see a slightly different form of `r+`:
 138
 139     @bors: r+ 38fe8d2 rollup
 140
 141 That additional `rollup` tells @bors that this change is eligible for a 'rollup'.
 142 To save @bors some work, and to get small changes through more quickly, when
 143 @bors attempts to merge a commit that's rollup-eligible, it will also merge
 144 the other rollup-eligible patches too, and they'll get tested and merged at
 145 the same time.
 146
 147 To find documentation-related issues, sort by the [A-docs label][adocs].
 148
 149 [adocs]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AA-docs
 150
 151 ## Issue Triage
 152
 153 Sometimes, an issue will stay open, even though the bug has been fixed. And
 154 sometimes, the original bug may go stale because something has changed in the
 155 meantime.
 156
 157 It can be helpful to go through older bug reports and make sure that they are
 158 still valid. Load up an older issue, double check that it's still true, and
 159 leave a comment letting us know if it is or is not. The [least recently
 160 updated sort][lru] is good for finding issues like this.
 161
 162 Contributors with sufficient permissions on the Rust repo can help by adding
 163 labels to triage issues:
 164
 165 * Yellow, **A**-prefixed labels state which **area** of the project an issue
 166   relates to.
 167
 168 * Magenta, **B**-prefixed labels identify bugs which **belong** elsewhere.
 169
 170 * Green, **E**-prefixed labels explain the level of **experience** necessary
 171   to fix the issue.
 172
 173 * Red, **I**-prefixed labels indicate the **importance** of the issue. The
 174   [I-nominated][inom] label indicates that an issue has been nominated for
 175   prioritizing at the next triage meeting.
 176
 177 * Orange, **P**-prefixed labels indicate a bug's **priority**. These labels
 178   are only assigned during triage meetings, and replace the [I-nominated][inom]
 179   label.
 180
 181 * Blue, **T**-prefixed bugs denote which **team** the issue belongs to.
 182
 183 * Dark blue, **beta-** labels track changes which need to be backported into
 184   the beta branches.
 185
 186 * The purple **metabug** label marks lists of bugs collected by other
 187   categories.
 188
 189 If you're looking for somewhere to start, check out the [E-easy][eeasy] tag.
 190
 191 [inom]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AI-nominated
 192 [eeasy]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AE-easy
 193 [lru]: https://github.com/rust-lang/rust/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-asc
 194
 195 ## Out-of-tree Contributions
 196
 197 There are a number of other ways to contribute to Rust that don't deal with
 198 this repository.
 199
 200 Answer questions in [#rust][pound-rust], or on [users.rust-lang.org][users],
 201 or on [StackOverflow][so].
 202
 203 Participate in the [RFC process](https://github.com/rust-lang/rfcs).
 204
 205 Find a [requested community library][community-library], build it, and publish
 206 it to [Crates.io](http://crates.io). Easier said than done, but very, very
 207 valuable!
 208
 209 [pound-rust]: http://chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust
 210 [users]: http://users.rust-lang.org/
 211 [so]: http://stackoverflow.com/questions/tagged/rust
 212 [community-library]: https://github.com/rust-lang/rfcs/labels/A-community-library