diff options
| -rw-r--r-- | CONTRIBUTING.md | 182 | ||||
| -rw-r--r-- | README.md | 9 | ||||
| -rw-r--r-- | src/doc/complement-bugreport.md | 61 | ||||
| -rw-r--r-- | src/librustc/README.txt | 4 |
4 files changed, 147 insertions, 109 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2724e479384..a4656dd415b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,60 +1,156 @@ -## How to submit a bug report +# Contributing to Rust -If you're just reporting a bug, please see: +Thank you for your interest in contributing to Rust! There are many ways to +contribute, and we appreciate all of them. This document is a bit long, so here's +links to the major sections: -http://doc.rust-lang.org/complement-bugreport.html +* [Feature Requests](#feature-requests) +* [Bug Reports](#bug-reports) +* [Pull Requests](#pull-requests) +* [Writing Documentation](#writing-documentation) +* [Issue Triage](#issue-triage) +* [Out-of-tree Contributions](#out-of-tree-contributions) -## Submitting an issue +If you have questions, please make a post on [internals.rust-lang.org][internals] or +hop on [#rust-internals][pound-rust-internals]. -Please submit issues here for bug reports or implementation details. For feature -requests, language changes, or major changes to the libraries, please submit an -issue against the [RFCs repository](https://github.com/rust-lang/rfcs). +As a reminder, all contributors are expected to follow our [Code of Conduct](coc). -## Pull request procedure +[pound-rust-internals]: http://chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust-internals +[internals]: http://internals.rust-lang.org +[coc]: http://www.rust-lang.org/conduct.html -Pull requests should be targeted at Rust's `master` branch. -Before pushing to your Github repo and issuing the pull request, -please do two things: +## Feature Requests -1. [Rebase](http://git-scm.com/book/en/Git-Branching-Rebasing) your - local changes against the `master` branch. Resolve any conflicts - that arise. +To request a change to the way that the Rust language works, please open an +issue in the [RFCs repository](https://github.com/rust-lang/rfcs/issues/new) +rather than this one. New features and other significant language changes +must go through the RFC process. -2. Run the full Rust test suite with the `make check` command. You're - not off the hook even if you just stick to documentation; code - examples in the docs are tested as well! Although for simple - wording or grammar fixes, this is probably unnecessary. +## Bug Reports -Pull requests will be treated as "review requests", and we will give -feedback we expect to see corrected on -[style](http://aturon.github.io/) and -substance before pulling. Changes contributed via pull request should -focus on a single issue at a time, like any other. We will not accept -pull-requests that try to "sneak" unrelated changes in. +While bugs are unfortunate, they're a reality in software. We can't fix what we +don't know about, so please report liberally. If you're not sure if something +is a bug or not, feel free to file a bug anyway. -Normally, all pull requests must include regression tests (see -[Note-testsuite](https://github.com/rust-lang/rust/wiki/Note-testsuite)) -that test your change. Occasionally, a change will be very difficult -to test for. In those cases, please include a note in your commit -message explaining why. +If you have the chance, before reporting a bug, please [search existing +issues](https://github.com/rust-lang/rust/search?q=&type=Issues&utf8=%E2%9C%93), +as it's possible that someone else has already reported your error. This doesn't +always work, and sometimes it's hard to know what to search for, so consider this +extra credit. We won't mind if you accidentally file a duplicate report. -In the licensing header at the beginning of any files you change, -please make sure the listed date range includes the current year. For -example, if it's 2014, and you change a Rust file that was created in -2010, it should begin: +Opening an issue is as easy as following [this +link](https://github.com/rust-lang/rust/issues/new) and filling out the fields. +Here's a template that you can use to file a bug, though it's not necessary to +use it exactly: -``` -// Copyright 2010-2014 The Rust Project Developers. + <short summary of the bug> + + I tried this code: + + <code sample that causes the bug> + + I expected to see this happen: <explanation> + + Instead, this happened: <explanation> + + ## Meta + + `rustc --version --verbose`: + + Backtrace: + +All three components are important: what you did, what you expected, what +happened instead. Please include the output of `rustc --version --verbose`, +which includes important information about what platform you're on, what +version of Rust you're using, etc. + +Sometimes, a backtrace is helpful, and so including that is nice. To get +a backtrace, set the `RUST_BACKTRACE` environment variable. The easiest way +to do this is to invoke `rustc` like this: + +```bash +$ RUST_BACKTRACE=1 rustc ... ``` -# Coordination and communication +## Pull Requests -Get feedback from other developers on -[internals.rust-lang.org][internals], and -[#rust-internals][pound-rust-internals]. +Pull requests are the primary mechanism we use to change Rust. GitHub itself +has some [great documentation][pull-requests] on using the Pull Request +feature. We use the 'fork and pull' model described there. -[pound-rust-internals]: http://chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust-internals -[internals]: http://internals.rust-lang.org +[pull-requests]: https://help.github.com/articles/using-pull-requests/ + +Please make pull requests against the `master` branch. + +All pull requests are reviewed by another person. We have a bot, +@rust-highfive, that will automatically assign a random person to review your request. + +If you want to request that a specific person reviews your pull request, +you can add an `r?` to the message. For example, Steve usually reviews +documentation changes. So if you were to make a documentation change, add + + r? @steveklabnik + +to the end of the message, and @rust-highfive will assign @steveklabnik instead +of a random person. This is entirely optional. + +After someone has reviewed your pull request, they will leave an annotation +on the pull request with an `r+`. It will look something like this: + + @bors: r+ 38fe8d2 + +This tells @bors, our lovable integration bot, that your pull request has +been approved. The PR then enters the [merge queue][merge-queue], where @bors +will run all the tests on every platform we support. If it all works out, +@bors will merge your code into `master` and close the pull request. + +[merge-queue]: http://buildbot.rust-lang.org/homu/queue/rust + +## Writing Documentation + +Documentation improvements are very welcome. The source of `doc.rust-lang.org` +is located in `src/doc` in the tree, and standard API documentation is generated +from the source code itself. + +Documentation pull requests function in the same as other pull requests, though +you may see a slightly different form of `r+`: + + @bors: r+ 38fe8d2 rollup + +That additional `rollup` tells @bors that this change is eligible for a 'rollup'. +To save @bors some work, and to get small changes through more quickly, when +@bors attempts to merge a commit that's rollup-eligible, it will also merge +the other rollup-eligible patches too, and they'll get tested and merged at +the same time. + +## Issue Triage + +Sometimes, an issue will stay open, even though the bug has been fixed. And +sometimes, the original bug may go stale because something has changed in the +meantime. + +It can be helpful to go through older bug reports and make sure that they are +still valid. Load up an older issue, double check that it's still true, and +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. + +[lru]: https://github.com/rust-lang/rust/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-asc + +## Out-of-tree Contributions + +There are a number of other ways to contribute to Rust that don't deal with +this repository. + +Answer questions in [#rust][pound-rust], or on [users.rust-lang.org][users], +or on [StackOverflow][so]. + +Participate in the [RFC process](https://github.com/rust-lang/rfcs). + +Find a [requested community library][community-library], build it, and publish +it to [Crates.io](http://crates.io). Easier said than done, but very, very +valuable! -For more details, please refer to -[Note-development-policy](https://github.com/rust-lang/rust/wiki/Note-development-policy). +[pound-rust]: http://chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust +[users]: http://users.rust-lang.org/ +[so]: http://stackoverflow.com/questions/tagged/rust +[community-library]: https://github.com/rust-lang/rfcs/labels/A-community-library diff --git a/README.md b/README.md index 9d7c939ff9d..065c4ed7c7b 100644 --- a/README.md +++ b/README.md @@ -18,6 +18,7 @@ Read ["Installing Rust"][install] from [The Book][trpl]. * GNU `make` 3.81 or later * `curl` * `git` + 2. Download and build Rust: You can either download a [tarball] or build directly from the [repo]. @@ -97,19 +98,21 @@ There is a lot more documentation in the [wiki]. [wiki]: https://github.com/rust-lang/rust/wiki -## Getting help and getting involved +## Getting help The Rust community congregates in a few places: * [StackOverflow] - Direct questions about using the language here. * [users.rust-lang.org] - General discussion, broader questions. -* [internals.rust-lang.org] - For development of the Rust language itself. * [/r/rust] - News and general discussion. [StackOverflow]: http://stackoverflow.com/questions/tagged/rust [/r/rust]: http://reddit.com/r/rust [users.rust-lang.org]: http://users.rust-lang.org/ -[internals.rust-lang.org]: http://internals.rust-lang.org/ + +## Contributing + +To contribute to Rust, please see [CONTRIBUTING.md](CONTRIBUTING.md). ## License diff --git a/src/doc/complement-bugreport.md b/src/doc/complement-bugreport.md deleted file mode 100644 index 1a28cd682e7..00000000000 --- a/src/doc/complement-bugreport.md +++ /dev/null @@ -1,61 +0,0 @@ -% How to submit a Rust bug report - -# I think I found a bug in the compiler! - -If you see this message: `error: internal compiler error: unexpected panic`, -then you have definitely found a bug in the compiler. It's also possible that -your code is not well-typed, but if you saw this message, it's still a bug in -error reporting. - -If you see a message about an LLVM assertion failure, then you have also -definitely found a bug in the compiler. In both of these cases, it's not your -fault and you should report a bug! - -If you see a compiler error message that you think is meant for users to see, -but it confuses you, *that's a bug too*. If it wasn't clear to you, then it's -an error message we want to improve, so please report it so that we can try -to make it better. - -# How do I know the bug I found isn't a bug that already exists in the issue tracker? - -If you don't have enough time for a search, then don't worry about that. Just submit -the bug. If it's a duplicate, somebody will notice that and close it during triage. - -If you have the time for it, it would be useful to type the text of the error -message you got [into the issue tracker search box](https://github.com/rust-lang/rust/issues) -to see if there's an existing bug that resembles your problem. If there is, -and it's an open bug, you can comment on that issue and say you are also affected. -This will encourage the devs to fix it. But again, don't let this stop you from -submitting a bug. We'd rather have to do the work of closing duplicates than -miss out on valid bug reports. - -# What information should I include in a bug report? - -It generally helps our diagnosis to include your specific OS (for example: Mac OS X 10.8.3, -Windows 7, Ubuntu 12.04) and your hardware architecture (for example: i686, x86_64). -It's also helpful to provide the exact version and host by copying the output of -re-running the erroneous rustc command with the `--version --verbose` flags, which will -produce something like this: - -```text -rustc 0.12.0 (ba4081a5a 2014-10-07 13:44:41 -0700) -binary: rustc -commit-hash: ba4081a5a8573875fed17545846f6f6902c8ba8d -commit-date: 2014-10-07 13:44:41 -0700 -host: i686-apple-darwin -release: 0.12.0 -``` - -Finally, if you can also provide a backtrace, that'd be great. You can get a -backtrace by setting the `RUST_BACKTRACE` environment variable to `1`, like -this: - -```bash -$ RUST_BACKTRACE=1 rustc ... -``` - -# I submitted a bug, but nobody has commented on it! - -This is sad, but does happen sometimes, since we're short-staffed. If you submit a -bug and you haven't received a comment on it within 3 business days, it's entirely -reasonable to ask about the status of the bug in #rust on irc.mozilla.org. diff --git a/src/librustc/README.txt b/src/librustc/README.txt index 697dddca74f..37097764f71 100644 --- a/src/librustc/README.txt +++ b/src/librustc/README.txt @@ -4,8 +4,8 @@ An informal guide to reading and working on the rustc compiler. If you wish to expand on this document, or have a more experienced Rust contributor add anything else to it, please get in touch: -https://github.com/rust-lang/rust/wiki/Note-development-policy -("Communication" subheading) +* http://internals.rust-lang.org/ +* https://chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust or file a bug: |