mikros/rust
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

CONTRIBUTING.md redux

Browse Source 
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 2015-02-13 12:26:44 -05:00
parent c5db290bf6
commit f645cad3a1
4 changed files with 156 additions and 118 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

200
CONTRIBUTING.md
View File

@ -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

9
README.md
View File

@ -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

61
src/doc/complement-bugreport.md
View File

@ -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
src/librustc/README.txt
View File

@ -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: