CONTRIBUTING.md

   1 # Contributing to Cargo
   2
   3 Thank you for your interest in contributing to Cargo! Good places to
   4 start are this document, [ARCHITECTURE.md](ARCHITECTURE.md), which
   5 describes the high-level structure of Cargo and [E-easy] bugs on the
   6 issue tracker.
   7
   8 If you have a general question about Cargo or it's internals, feel free to ask
   9 on [Discord].
  10
  11 ## Code of Conduct
  12
  13 All contributors are expected to follow our [Code of Conduct].
  14
  15 ## Bug reports
  16
  17 We can't fix what we don't know about, so please report problems liberally. This
  18 includes problems with understanding the documentation, unhelpful error messages
  19 and unexpected behavior.
  20
  21 **If you think that you have identified an issue with Cargo that might compromise
  22 its users' security, please do not open a public issue on GitHub. Instead,
  23 we ask you to refer to Rust's [security policy].**
  24
  25 Opening an issue is as easy as following [this link][new-issues] and filling out
  26 the fields. Here's a template that you can use to file an issue, though it's not
  27 necessary to use it exactly:
  28
  29     <short summary of the problem>
  30
  31     I tried this: <minimal example that causes the problem>
  32
  33     I expected to see this happen: <explanation>
  34
  35     Instead, this happened: <explanation>
  36
  37     I'm using <output of `cargo --version`>
  38
  39 All three components are important: what you did, what you expected, what
  40 happened instead. Please use https://gist.github.com/ if your examples run long.
  41
  42
  43 ## Feature requests
  44
  45 Cargo follows the general Rust model of evolution. All major features go through
  46 an RFC process. Therefore, before opening a feature request issue create a
  47 Pre-RFC thread on the [internals][irlo] forum to get preliminary feedback.
  48 Implementing a feature as a [custom subcommand][subcommands] is encouraged as it
  49 helps demonstrate the demand for the functionality and is a great way to deliver
  50 a working solution faster as it can iterate outside of cargo's release cadence.
  51
  52 ## Working on issues
  53
  54 If you're looking for somewhere to start, check out the [E-easy][E-Easy] and
  55 [E-mentor][E-mentor] tags.
  56
  57 Feel free to ask for guidelines on how to tackle a problem on [Discord] or open a
  58 [new issue][new-issues]. This is especially important if you want to add new
  59 features to Cargo or make large changes to the already existing code-base.
  60 Cargo's core developers will do their best to provide help.
  61
  62 If you start working on an already-filed issue, post a comment on this issue to
  63 let people know that somebody is working it. Feel free to ask for comments if
  64 you are unsure about the solution you would like to submit.
  65
  66 While Cargo does make use of some Rust-features available only through the
  67 `nightly` toolchain, it must compile on stable Rust. Code added to Cargo
  68 is encouraged to make use of the latest stable features of the language and
  69 `stdlib`.
  70
  71 We use the "fork and pull" model [described here][development-models], where
  72 contributors push changes to their personal fork and create pull requests to
  73 bring those changes into the source repository. This process is partly
  74 automated: Pull requests are made against Cargo's master-branch, tested and
  75 reviewed. Once a change is approved to be merged, a friendly bot merges the
  76 changes into an internal branch, runs the full test-suite on that branch
  77 and only then merges into master. This ensures that Cargo's master branch
  78 passes the test-suite at all times.
  79
  80 Your basic steps to get going:
  81
  82 * Fork Cargo and create a branch from master for the issue you are working on.
  83 * Please adhere to the code style that you see around the location you are
  84 working on.
  85 * [Commit as you go][githelp].
  86 * Include tests that cover all non-trivial code. The existing tests
  87 in `test/` provide templates on how to test Cargo's behavior in a
  88 sandbox-environment. The internal module `crates/cargo-test-support` provides a vast amount
  89 of helpers to minimize boilerplate. See [`crates/cargo-test-support/src/lib.rs`] for an
  90 introduction to writing tests.
  91 * Make sure `cargo test` passes. See [Running tests](#running-tests) below
  92 for details on running tests.
  93 * All code changes are expected to comply with the formatting suggested by `rustfmt`.
  94 You can use `rustup component add rustfmt` to install `rustfmt` and use
  95 `cargo fmt` to automatically format your code.
  96 * Push your commits to GitHub and create a pull request against Cargo's
  97 `master` branch.
  98
  99 ## Running tests
 100
 101 Most of the tests are found in the `testsuite` integration test. This can be
 102 run with a simple `cargo test`.
 103
 104 Some tests only run on the nightly toolchain, and will be ignored on other
 105 channels. It is recommended that you run tests with both nightly and stable to
 106 ensure everything is working as expected.
 107
 108 Some tests exercise cross compiling to a different target. This will require
 109 you to install the appropriate target. This typically is the 32-bit target of
 110 your host platform. For example, if your host is a 64-bit
 111 `x86_64-unknown-linux-gnu`, then you should install the 32-bit target with
 112 `rustup target add i686-unknown-linux-gnu`. If you don't have the alternate
 113 target installed, there should be an error message telling you what to do. You
 114 may also need to install additional tools for the target. For example, on Ubuntu
 115 you should install the `gcc-multilib` package.
 116
 117 If you can't install an alternate target, you can set the
 118 `CFG_DISABLE_CROSS_TESTS=1` environment variable to disable these tests. The
 119 Windows cross tests only support the MSVC toolchain.
 120
 121 Some of the nightly tests require the `rustc-dev` and `llvm-tools-preview`
 122 rustup components installed. These components include the compiler as a
 123 library. This may already be installed with your nightly toolchain, but if it
 124 isn't, run `rustup component add rustc-dev llvm-tools-preview
 125 --toolchain=nightly`.
 126
 127 There are several other packages in the repo for running specialized tests,
 128 and you will need to run these tests separately by changing into its directory
 129 and running `cargo test`:
 130
 131 * [`crates/resolver-tests`] – This package runs tests on the dependency resolver.
 132 * [`crates/cargo-platform`] – This is a standalone `cfg()` expression parser.
 133
 134 The `build-std` tests are disabled by default, but you can run them by setting
 135 the `CARGO_RUN_BUILD_STD_TESTS=1` environment variable and running `cargo test
 136 --test build-std`. This requires the nightly channel, and also requires the
 137 `rust-src` component installed with `rustup component add rust-src
 138 --toolchain=nightly`.
 139
 140 [`crates/resolver-tests`]: crates/resolver-tests
 141 [`crates/cargo-platform`]: crates/cargo-platform
 142
 143 ## Pull requests
 144
 145 After the pull request is made, a friendly bot will automatically assign a
 146 reviewer; the review-process will make sure that the proposed changes are
 147 sound. Please give the assigned reviewer sufficient time, especially during
 148 weekends. If you don't get a reply, you may poke the core developers on [Discord].
 149
 150 A merge of Cargo's master-branch and your changes is immediately queued
 151 to be tested after the pull request is made. In case unforeseen
 152 problems are discovered during this step (e.g., a failure on a platform you
 153 originally did not develop on), you may ask for guidance. Push additional
 154 commits to your branch to tackle these problems.
 155
 156 The reviewer might point out changes deemed necessary. Please add them as
 157 extra commits; this ensures that the reviewer can see what has changed since
 158 the code was previously reviewed. Large or tricky changes may require several
 159 passes of review and changes.
 160
 161 Once the reviewer approves your pull request, a friendly bot picks it up
 162 and [merges][mergequeue] it into Cargo's `master` branch.
 163
 164 ## Contributing to the documentation
 165
 166 See the [documentation README](src/doc/README.md) for details on building the
 167 documentation.
 168
 169 ## Issue Triage
 170
 171 Sometimes an issue will stay open, even though the bug has been fixed. And
 172 sometimes, the original bug may go stale because something has changed in the
 173 meantime.
 174
 175 It can be helpful to go through older bug reports and make sure that they are
 176 still valid. Load up an older issue, double check that it's still true, and
 177 leave a comment letting us know if it is or is not. The [least recently
 178 updated sort][lru] is good for finding issues like this.
 179
 180 Contributors with sufficient permissions on the Rust-repository can help by
 181 adding labels to triage issues:
 182
 183 * Yellow, **A**-prefixed labels state which **area** of the project an issue
 184   relates to.
 185
 186 * Magenta, **B**-prefixed labels identify bugs which are **blockers**.
 187
 188 * Light purple, **C**-prefixed labels represent the **category** of an issue.
 189   In particular, **C-feature-request** marks *proposals* for new features. If
 190   an issue is **C-feature-request**, but is not **Feature accepted** or **I-nominated**,
 191   then it was not thoroughly discussed, and might need some additional design
 192   or perhaps should be implemented as an external subcommand first. Ping
 193   @rust-lang/cargo if you want to send a PR for such issue.
 194
 195 * Dark purple, **Command**-prefixed labels mean the issue has to do with a
 196   specific cargo command.
 197
 198 * Green, **E**-prefixed labels explain the level of **experience** or
 199   **effort** necessary to fix the issue. [**E-mentor**][E-mentor] issues also
 200   have some instructions on how to get started.
 201
 202 * Red, **I**-prefixed labels indicate the **importance** of the issue. The
 203   **[I-nominated][]** label indicates that an issue has been nominated for
 204   prioritizing at the next triage meeting.
 205
 206 * Purple gray, **O**-prefixed labels are the **operating system** or platform
 207   that this issue is specific to.
 208
 209 * Orange, **P**-prefixed labels indicate a bug's **priority**. These labels
 210   are only assigned during triage meetings and replace the **[I-nominated][]**
 211   label.
 212
 213 * The light orange **relnotes** label marks issues that should be documented in
 214   the release notes of the next release.
 215
 216 * Dark blue, **Z**-prefixed labels are for unstable, nightly features.
 217
 218 [githelp]: https://dont-be-afraid-to-commit.readthedocs.io/en/latest/git/commandlinegit.html
 219 [development-models]: https://help.github.com/articles/about-collaborative-development-models/
 220 [gist]: https://gist.github.com/
 221 [new-issues]: https://github.com/rust-lang/cargo/issues/new
 222 [mergequeue]: https://buildbot2.rust-lang.org/homu/queue/cargo
 223 [security policy]: https://www.rust-lang.org/security.html
 224 [lru]: https://github.com/rust-lang/cargo/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-asc
 225 [E-easy]: https://github.com/rust-lang/cargo/labels/E-easy
 226 [E-mentor]: https://github.com/rust-lang/cargo/labels/E-mentor
 227 [I-nominated]: https://github.com/rust-lang/cargo/labels/I-nominated
 228 [Code of Conduct]: https://www.rust-lang.org/conduct.html
 229 [Discord]: https://discordapp.com/invite/rust-lang
 230 [`crates/cargo-test-support/src/lib.rs`]: crates/cargo-test-support/src/lib.rs
 231 [irlo]: https://internals.rust-lang.org/
 232 [subcommands]: https://doc.rust-lang.org/cargo/reference/external-tools.html#custom-subcommands