Skip to content

Commit

Permalink
Auto merge of #4554 - lukaslueg:contributing, r=alexcrichton
Browse files Browse the repository at this point in the history 
Expand contribution guidelines

Expand `contributing.md`, including inspirations from Rust's and some other projects' guides.
  • Loading branch information
@bors
bors committed Sep 30, 2017
2 parents 6e69e09 + 47faa0f commit a888e11
Showing 1 changed file with 109 additions and 27 deletions.
136 changes: 109 additions & 27 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,32 +2,114 @@

Thank you for your interest in contributing to Cargo! Good places to
start are this document, [ARCHITECTURE.md](ARCHITECTURE.md), which
describes high-level structure of Cargo and [E-easy] bugs on the
describes the high-level structure of Cargo and [E-easy] bugs on the
issue tracker.

As a reminder, all contributors are expected to follow our [Code of Conduct].
If you have a general question about Cargo or it's internals, feel free to ask
on [IRC].

[E-easy]: https://github.com/rust-lang/cargo/labels/E-easy
[Code of Conduct]: https://www.rust-lang.org/conduct.html
## Code of Conduct

All contributors are expected to follow our [Code of Conduct].

## Bug reports

We can't fix what we don't know about, so please report problems liberally. This
includes problems with understanding the documentation, unhelpful error messages
and unexpected behavior.

**If you think that you have identified an issue with Cargo that might compromise
its users' security, please do not open a public issue on GitHub. Instead,
we ask you to refer to Rust's [security policy].**

Opening an issue is as easy as following [this
link][new-issues] and filling out the fields.
Here's a template that you can use to file an issue, though it's not necessary to
use it exactly:

<short summary of the problem>

I tried this: <minimal example that causes the problem>

I expected to see this happen: <explanation>

Instead, this happened: <explanation>

I'm using <output of `cargo --version`>

All three components are important: what you did, what you expected, what
happened instead. Please use https://gist.github.com/ if your examples run long.

## Working on issues

## Running the tests
If you're looking for somewhere to start, check out the [E-easy][E-Easy] tag.

To run Cargo's tests, use `cargo test`. If you do not have the cross-compilers
installed locally, ignore the cross-compile test failures, or disable them by
Feel free to ask for guidelines on how to tackle a problem on [IRC] or open a
[new issue][new-issues]. This is especially important if you want to add new
features to Cargo or make large changes to the already existing code-base.
Cargo's core developers will do their best to provide help.

If you start working on an already-filed issue, post a comment on this issue to
let people know that somebody is working it. Feel free to ask for comments if
you are unsure about the solution you would like to submit.

While Cargo does make use of some Rust-features available only through the
`nightly` toolchain, it must compile on stable Rust. Code added to Cargo
is encouraged to make use of the latest stable features of the language and
`stdlib`.

We use the "fork and pull" model [described here][development-models], where
contributors push changes to their personal fork and create pull requests to
bring those changes into the source repository. This process is partly
automated: Pull requests are made against Cargo's master-branch, tested and
reviewed. Once a change is approved to be merged, a friendly bot merges the
changes into an internal branch, runs the full test-suite on that branch
and only then merges into master. This ensures that Cargo's master branch
passes the test-suite at all times.

Your basic steps to get going:

* Fork Cargo and create a branch from master for the issue you are working on.
* Please adhere to the code style that you see around the location you are
working on.
* [Commit as you go][githelp].
* Include tests that cover all non-trivial code. The existing tests
in `test/` provide templates on how to test Cargo's behavior in a
sandbox-environment. The internal crate `cargotest` provides a vast amount
of helpers to minimize boilerplate.
* Make sure `cargo test` passes. If you do not have the cross-compilers
installed locally, ignore the cross-compile test failures or disable them by
using `CFG_DISABLE_CROSS_TESTS=1 cargo test`. Note that some tests are enabled
only on nightly toolchain.
only on `nightly` toolchain. If you can, test both toolchains.
* Push your commits to GitHub and create a pull request against Cargo's
`master` branch.

## Pull requests

After the pull request is made, a friendly bot will automatically assign a
reviewer; the review-process will make sure that the proposed changes are
sound. Please give the assigned reviewer sufficient time, especially during
weekends. If you don't get a reply, you may poke the core developers on [IRC].

## Minimal version of Rust
A merge of Cargo's master-branch and your changes is immediately queued
to be tested after the pull request is made. In case unforeseen
problems are discovered during this step (e.g. a failure on a platform you
originally did not develop on), you may ask for guidance. Push additional
commits to your branch to tackle these problems.

Cargo must compile on stable Rust. Code added to Cargo is encouraged to use
the latest stable features of the language and `stdlib`.
The reviewer might point out changes deemed necessary. Please add them as
extra commits; this ensures that the reviewer can see what has changed since
the code was previously reviewed. Large or tricky changes may require several
passes of review and changes.

## Contributing to the Docs
Once the reviewer approves your pull request, a friendly bot picks it up
and [merges][mergequeue] it into Cargo's `master` branch.

To contribute to the docs, all you need to do is change the markdown files in
the `src/doc` directory. To view the rendered version of changes you have
made locally, run:
## Contributing to the documentation

To contribute to the documentation, all you need to do is change the markdown
files in the `src/doc` directory. To view the rendered version of changes you
have made locally, run:

```sh
sh src/ci/dox.sh
Expand All @@ -37,7 +119,7 @@ open target/doc/index.html

## Issue Triage

Sometimes, an issue will stay open, even though the bug has been fixed. And
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.

Expand All @@ -46,8 +128,8 @@ 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.

Contributors with sufficient permissions on the Rust repo can help by adding
labels to triage issues:
Contributors with sufficient permissions on the Rust-repository can help by
adding labels to triage issues:

* Yellow, **A**-prefixed labels state which **area** of the project an issue
relates to.
Expand All @@ -70,20 +152,20 @@ labels to triage issues:
that this issue is specific to.

* Orange, **P**-prefixed labels indicate a bug's **priority**. These labels
are only assigned during triage meetings, and replace the [I-nominated][inom]
are only assigned during triage meetings and replace the [I-nominated][inom]
label.

* The light orange **relnotes** label marks issues that should be documented in
the release notes of the next release.

If you're looking for somewhere to start, check out the [E-easy][eeasy] tag.

[eeasy]: https://github.com/rust-lang/cargo/issues?q=is%3Aopen+is%3Aissue+label%3AE-easy
[githelp]: https://dont-be-afraid-to-commit.readthedocs.io/en/latest/git/commandlinegit.html
[development-models]: https://help.github.com/articles/about-collaborative-development-models/
[gist]: https://gist.github.com/
[new-issues]: https://github.com/rust-lang/cargo/issues/new
[mergequeue]: https://buildbot2.rust-lang.org/homu/queue/cargo
[security policy]: https://www.rust-lang.org/security.html
[lru]: https://github.com/rust-lang/cargo/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-asc

## Getting help

If you need some pointers about Cargo's internals, feel free to ask questions
on the relevant issue or on the [IRC].

[E-easy]: https://github.com/rust-lang/cargo/labels/E-easy
[Code of Conduct]: https://www.rust-lang.org/conduct.html
[IRC]: https://kiwiirc.com/client/irc.mozilla.org/cargo

0 comments on commit a888e11

Please sign in to comment.