issue tracker.
If you have a general question about Cargo or it's internals, feel free to ask
-on [IRC].
+on [Discord].
## Code of Conduct
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
+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>
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.
+
+## Feature requests
+
+Cargo follows the general Rust model of evolution. All major features go through
+an RFC process. Therefore, before opening a feature request issue create a
+Pre-RFC thread on the [internals][irlo] forum to get preliminary feedback.
+Implementing a feature as a [custom subcommand][subcommands] is encouraged as it
+helps demonstrate the demand for the functionality and is a great way to deliver
+a working solution faster as it can iterate outside of cargo's release cadence.
+
## Working on issues
-If you're looking for somewhere to start, check out the [E-easy][E-Easy] and
+If you're looking for somewhere to start, check out the [E-easy][E-Easy] and
[E-mentor][E-mentor] tags.
-Feel free to ask for guidelines on how to tackle a problem on [IRC] or open a
+Feel free to ask for guidelines on how to tackle a problem on [Discord] 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.
* [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. If you can, test both toolchains.
+sandbox-environment. The internal module `crates/cargo-test-support` provides a vast amount
+of helpers to minimize boilerplate. See [`crates/cargo-test-support/src/lib.rs`] for an
+introduction to writing tests.
+* Make sure `cargo test` passes. See [Running tests](#running-tests) below
+for details on running tests.
* All code changes are expected to comply with the formatting suggested by `rustfmt`.
-You can use `rustup +stable component add rustfmt-preview` to install `rustfmt` and use
-`rustfmt +stable --skip-children $FILE` on the changed files to automatically format your code.
+You can use `rustup component add rustfmt` to install `rustfmt` and use
+`cargo fmt` to automatically format your code.
* Push your commits to GitHub and create a pull request against Cargo's
`master` branch.
+## Running tests
+
+Most of the tests are found in the `testsuite` integration test. This can be
+run with a simple `cargo test`.
+
+Some tests only run on the nightly toolchain, and will be ignored on other
+channels. It is recommended that you run tests with both nightly and stable to
+ensure everything is working as expected.
+
+Some tests exercise cross compiling to a different target. This will require
+you to install the appropriate target. This typically is the 32-bit target of
+your host platform. For example, if your host is a 64-bit
+`x86_64-unknown-linux-gnu`, then you should install the 32-bit target with
+`rustup target add i686-unknown-linux-gnu`. If you don't have the alternate
+target installed, there should be an error message telling you what to do. You
+may also need to install additional tools for the target. For example, on Ubuntu
+you should install the `gcc-multilib` package.
+
+If you can't install an alternate target, you can set the
+`CFG_DISABLE_CROSS_TESTS=1` environment variable to disable these tests. The
+Windows cross tests only support the MSVC toolchain.
+
+Some of the nightly tests require the `rustc-dev` and `llvm-tools-preview`
+rustup components installed. These components include the compiler as a
+library. This may already be installed with your nightly toolchain, but if it
+isn't, run `rustup component add rustc-dev llvm-tools-preview
+--toolchain=nightly`.
+
+There are several other packages in the repo for running specialized tests,
+and you will need to run these tests separately by changing into its directory
+and running `cargo test`:
+
+* [`crates/resolver-tests`] – This package runs tests on the dependency resolver.
+* [`crates/cargo-platform`] – This is a standalone `cfg()` expression parser.
+
+The `build-std` tests are disabled by default, but you can run them by setting
+the `CARGO_RUN_BUILD_STD_TESTS=1` environment variable and running `cargo test
+--test build-std`. This requires the nightly channel, and also requires the
+`rust-src` component installed with `rustup component add rust-src
+--toolchain=nightly`.
+
+[`crates/resolver-tests`]: crates/resolver-tests
+[`crates/cargo-platform`]: crates/cargo-platform
+
## 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].
+weekends. If you don't get a reply, you may poke the core developers on [Discord].
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
+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.
## 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, make sure you have `mdbook` installed and run:
-
-```sh
-cd src/doc
-mdbook build
-open book/index.html
-```
-
-To install `mdbook` run `cargo install mdbook`.
-
+See the [documentation README](src/doc/README.md) for details on building the
+documentation.
## Issue Triage
* Magenta, **B**-prefixed labels identify bugs which are **blockers**.
* Light purple, **C**-prefixed labels represent the **category** of an issue.
+ In particular, **C-feature-request** marks *proposals* for new features. If
+ an issue is **C-feature-request**, but is not **Feature accepted** or **I-nominated**,
+ then it was not thoroughly discussed, and might need some additional design
+ or perhaps should be implemented as an external subcommand first. Ping
+ @rust-lang/cargo if you want to send a PR for such issue.
* Dark purple, **Command**-prefixed labels mean the issue has to do with a
specific cargo command.
* The light orange **relnotes** label marks issues that should be documented in
the release notes of the next release.
+* Dark blue, **Z**-prefixed labels are for unstable, nightly features.
[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/
[E-mentor]: https://github.com/rust-lang/cargo/labels/E-mentor
[I-nominated]: https://github.com/rust-lang/cargo/labels/I-nominated
[Code of Conduct]: https://www.rust-lang.org/conduct.html
-[IRC]: https://kiwiirc.com/client/irc.mozilla.org/cargo
+[Discord]: https://discordapp.com/invite/rust-lang
+[`crates/cargo-test-support/src/lib.rs`]: crates/cargo-test-support/src/lib.rs
+[irlo]: https://internals.rust-lang.org/
+[subcommands]: https://doc.rust-lang.org/cargo/reference/external-tools.html#custom-subcommands
projects / cargo.git / blobdiff