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 * [Helpful Links and Information](#helpful-links-and-information)
  14
  15 If you have questions, please make a post on [internals.rust-lang.org][internals] or
  16 hop on [#rust-internals][pound-rust-internals].
  17
  18 As a reminder, all contributors are expected to follow our [Code of Conduct][coc].
  19
  20 [pound-rust-internals]: http://chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust-internals
  21 [internals]: https://internals.rust-lang.org
  22 [coc]: https://www.rust-lang.org/conduct.html
  23
  24 ## Feature Requests
  25
  26 To request a change to the way that the Rust language works, please open an
  27 issue in the [RFCs repository](https://github.com/rust-lang/rfcs/issues/new)
  28 rather than this one. New features and other significant language changes
  29 must go through the RFC process.
  30
  31 ## Bug Reports
  32
  33 While bugs are unfortunate, they're a reality in software. We can't fix what we
  34 don't know about, so please report liberally. If you're not sure if something
  35 is a bug or not, feel free to file a bug anyway.
  36
  37 **If you believe reporting your bug publicly represents a security risk to Rust users,
  38 please follow our [instructions for reporting security vulnerabilities](https://www.rust-lang.org/security.html)**.
  39
  40 If you have the chance, before reporting a bug, please [search existing
  41 issues](https://github.com/rust-lang/rust/search?q=&type=Issues&utf8=%E2%9C%93),
  42 as it's possible that someone else has already reported your error. This doesn't
  43 always work, and sometimes it's hard to know what to search for, so consider this
  44 extra credit. We won't mind if you accidentally file a duplicate report.
  45
  46 Opening an issue is as easy as following [this
  47 link](https://github.com/rust-lang/rust/issues/new) and filling out the fields.
  48 Here's a template that you can use to file a bug, though it's not necessary to
  49 use it exactly:
  50
  51     <short summary of the bug>
  52
  53     I tried this code:
  54
  55     <code sample that causes the bug>
  56
  57     I expected to see this happen: <explanation>
  58
  59     Instead, this happened: <explanation>
  60
  61     ## Meta
  62
  63     `rustc --version --verbose`:
  64
  65     Backtrace:
  66
  67 All three components are important: what you did, what you expected, what
  68 happened instead. Please include the output of `rustc --version --verbose`,
  69 which includes important information about what platform you're on, what
  70 version of Rust you're using, etc.
  71
  72 Sometimes, a backtrace is helpful, and so including that is nice. To get
  73 a backtrace, set the `RUST_BACKTRACE` environment variable. The easiest way
  74 to do this is to invoke `rustc` like this:
  75
  76 ```bash
  77 $ RUST_BACKTRACE=1 rustc ...
  78 ```
  79
  80 ## Pull Requests
  81
  82 Pull requests are the primary mechanism we use to change Rust. GitHub itself
  83 has some [great documentation][pull-requests] on using the Pull Request
  84 feature. We use the 'fork and pull' model described there.
  85
  86 [pull-requests]: https://help.github.com/articles/using-pull-requests/
  87
  88 Please make pull requests against the `master` branch.
  89
  90 Compiling all of `make check` can take a while. When testing your pull request,
  91 consider using one of the more specialized `make` targets to cut down on the
  92 amount of time you have to wait. You need to have built the compiler at least
  93 once before running these will work, but that’s only one full build rather than
  94 one each time.
  95
  96     $ make -j8 rustc-stage1 && make check-stage1
  97
  98 is one such example, which builds just `rustc`, and then runs the tests. If
  99 you’re adding something to the standard library, try
 100
 101     $ make -j8 check-stage1-std NO_REBUILD=1
 102
 103 This will not rebuild the compiler, but will run the tests.
 104
 105 All pull requests are reviewed by another person. We have a bot,
 106 @rust-highfive, that will automatically assign a random person to review your
 107 request.
 108
 109 If you want to request that a specific person reviews your pull request,
 110 you can add an `r?` to the message. For example, Steve usually reviews
 111 documentation changes. So if you were to make a documentation change, add
 112
 113     r? @steveklabnik
 114
 115 to the end of the message, and @rust-highfive will assign @steveklabnik instead
 116 of a random person. This is entirely optional.
 117
 118 After someone has reviewed your pull request, they will leave an annotation
 119 on the pull request with an `r+`. It will look something like this:
 120
 121     @bors: r+ 38fe8d2
 122
 123 This tells @bors, our lovable integration bot, that your pull request has
 124 been approved. The PR then enters the [merge queue][merge-queue], where @bors
 125 will run all the tests on every platform we support. If it all works out,
 126 @bors will merge your code into `master` and close the pull request.
 127
 128 [merge-queue]: http://buildbot.rust-lang.org/homu/queue/rust
 129
 130 Speaking of tests, Rust has a comprehensive test suite. More information about
 131 it can be found
 132 [here](https://github.com/rust-lang/rust-wiki-backup/blob/master/Note-testsuite.md).
 133
 134 ## Writing Documentation
 135
 136 Documentation improvements are very welcome. The source of `doc.rust-lang.org`
 137 is located in `src/doc` in the tree, and standard API documentation is generated
 138 from the source code itself.
 139
 140 Documentation pull requests function in the same way as other pull requests,
 141 though you may see a slightly different form of `r+`:
 142
 143     @bors: r+ 38fe8d2 rollup
 144
 145 That additional `rollup` tells @bors that this change is eligible for a 'rollup'.
 146 To save @bors some work, and to get small changes through more quickly, when
 147 @bors attempts to merge a commit that's rollup-eligible, it will also merge
 148 the other rollup-eligible patches too, and they'll get tested and merged at
 149 the same time.
 150
 151 To find documentation-related issues, sort by the [A-docs label][adocs].
 152
 153 [adocs]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AA-docs
 154
 155 In many cases, you don't need a full `make doc`. You can use `rustdoc` directly
 156 to check small fixes. For example, `rustdoc src/doc/reference.md` will render
 157 reference to `doc/reference.html`. The CSS might be messed up, but you can
 158 verify that HTML is right.
 159
 160 ## Issue Triage
 161
 162 Sometimes, an issue will stay open, even though the bug has been fixed. And
 163 sometimes, the original bug may go stale because something has changed in the
 164 meantime.
 165
 166 It can be helpful to go through older bug reports and make sure that they are
 167 still valid. Load up an older issue, double check that it's still true, and
 168 leave a comment letting us know if it is or is not. The [least recently
 169 updated sort][lru] is good for finding issues like this.
 170
 171 Contributors with sufficient permissions on the Rust repo can help by adding
 172 labels to triage issues:
 173
 174 * Yellow, **A**-prefixed labels state which **area** of the project an issue
 175   relates to.
 176
 177 * Magenta, **B**-prefixed labels identify bugs which are **blockers**.
 178
 179 * Green, **E**-prefixed labels explain the level of **experience** necessary
 180   to fix the issue.
 181
 182 * Red, **I**-prefixed labels indicate the **importance** of the issue. The
 183   [I-nominated][inom] label indicates that an issue has been nominated for
 184   prioritizing at the next triage meeting.
 185
 186 * Orange, **P**-prefixed labels indicate a bug's **priority**. These labels
 187   are only assigned during triage meetings, and replace the [I-nominated][inom]
 188   label.
 189
 190 * Blue, **T**-prefixed bugs denote which **team** the issue belongs to.
 191
 192 * Dark blue, **beta-** labels track changes which need to be backported into
 193   the beta branches.
 194
 195 * The purple **metabug** label marks lists of bugs collected by other
 196   categories.
 197
 198 If you're looking for somewhere to start, check out the [E-easy][eeasy] tag.
 199
 200 [inom]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AI-nominated
 201 [eeasy]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AE-easy
 202 [lru]: https://github.com/rust-lang/rust/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-asc
 203
 204 ## Out-of-tree Contributions
 205
 206 There are a number of other ways to contribute to Rust that don't deal with
 207 this repository.
 208
 209 Answer questions in [#rust][pound-rust], or on [users.rust-lang.org][users],
 210 or on [StackOverflow][so].
 211
 212 Participate in the [RFC process](https://github.com/rust-lang/rfcs).
 213
 214 Find a [requested community library][community-library], build it, and publish
 215 it to [Crates.io](http://crates.io). Easier said than done, but very, very
 216 valuable!
 217
 218 [pound-rust]: http://chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust
 219 [users]: https://users.rust-lang.org/
 220 [so]: http://stackoverflow.com/questions/tagged/rust
 221 [community-library]: https://github.com/rust-lang/rfcs/labels/A-community-library
 222
 223 ## Helpful Links and Information
 224
 225 For people new to Rust, and just starting to contribute, or even for
 226 more seasoned developers, some useful places to look for information
 227 are:
 228
 229 * The [Rust Internals forum][rif], a place to ask questions and
 230   discuss Rust's internals
 231 * The [generated documentation for rust's compiler][gdfrustc]
 232 * The [rust reference][rr], even though it doesn't specifically talk about Rust's internals, it's a great resource nonetheless
 233 * Although out of date, [Tom Lee's great blog article][tlgba] is very helpful
 234 * [rustaceans.org][ro] is helpful, but mostly dedicated to IRC
 235 * The [Rust Compiler Testing Docs][rctd]
 236 * For @bors, [this cheat sheet][cheatsheet] is helpful (Remember to replace `@homu` with `@bors` in the commands that you use.)
 237 * **Google!** ([search only in Rust Documentation][gsearchdocs] to find types, traits, etc. quickly)
 238 * Don't be afraid to ask! The Rust community is friendly and helpful.
 239
 240 [gdfrustc]: http://manishearth.github.io/rust-internals-docs/rustc/
 241 [gsearchdocs]: https://www.google.com/search?q=site:doc.rust-lang.org+your+query+here
 242 [rif]: http://internals.rust-lang.org
 243 [rr]: https://doc.rust-lang.org/book/README.html
 244 [tlgba]: http://tomlee.co/2014/04/03/a-more-detailed-tour-of-the-rust-compiler/
 245 [ro]: http://www.rustaceans.org/
 246 [rctd]: ./COMPILER_TESTS.md
 247 [cheatsheet]: http://buildbot.rust-lang.org/homu/