From 47faa0f17101efa417feddd99d65315c42cdd0f1 Mon Sep 17 00:00:00 2001 From: Lukas Lueg Date: Fri, 29 Sep 2017 22:31:14 +0200 Subject: [PATCH] Expand contribution guidelines --- CONTRIBUTING.md | 136 ++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 109 insertions(+), 27 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cb0618b15fd..62c0ea591fe 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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: + + + + I tried this: + + I expected to see this happen: + + Instead, this happened: + + I'm using + +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 @@ -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. @@ -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. @@ -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