mirror of
https://github.com/rust-lang/rust
synced 2024-09-05 16:57:03 +00:00
CONTRIBUTING.md redux
This redux of CONTRIBUTING.md adds in more information, including subsuming both compliment-bugreport.md and Note-development-policy in the wiki. I only glanced at the broad TOC of Note-development-policy, and did not use the text as the basis for the re-write. This will then address the last outstanding part of #5831.
This commit is contained in:
Steve Klabnik
parent
c5db290bf6
commit
f645cad3a1
200
CONTRIBUTING.md
200
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).
|
||||
|
||||
## Pull request procedure
|
||||
|
||||
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:
|
||||
|
||||
1. [Rebase](http://git-scm.com/book/en/Git-Branching-Rebasing) your
|
||||
local changes against the `master` branch. Resolve any conflicts
|
||||
that arise.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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:
|
||||
|
||||
```
|
||||
// Copyright 2010-2014 The Rust Project Developers.
|
||||
```
|
||||
|
||||
# Coordination and communication
|
||||
|
||||
Get feedback from other developers on
|
||||
[internals.rust-lang.org][internals], and
|
||||
[#rust-internals][pound-rust-internals].
|
||||
As a reminder, all contributors are expected to follow our [Code of Conduct](coc).
|
||||
|
||||
[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
|
||||
|
||||
For more details, please refer to
|
||||
[Note-development-policy](https://github.com/rust-lang/rust/wiki/Note-development-policy).
|
||||
## Feature Requests
|
||||
|
||||
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.
|
||||
|
||||
## Bug Reports
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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:
|
||||
|
||||
<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 ...
|
||||
```
|
||||
|
||||
## Pull Requests
|
||||
|
||||
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.
|
||||
|
||||
[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!
|
||||
|
||||
[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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
@ -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:
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue