1 # Contributing to Cargo
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
8 If you have a general question about Cargo or it's internals, feel free to ask
13 All contributors are expected to follow our [Code of Conduct].
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.
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].**
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:
29 <short summary of the problem>
31 I tried this: <minimal example that causes the problem>
33 I expected to see this happen: <explanation>
35 Instead, this happened: <explanation>
37 I'm using <output of `cargo --version`>
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.
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.
54 If you're looking for somewhere to start, check out the [E-easy][E-Easy] and
55 [E-mentor][E-mentor] tags.
57 Feel free to ask for guidelines on how to tackle a problem on [IRC] 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.
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.
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
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.
80 Your basic steps to get going:
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
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 crate `cargotest` provides a vast amount
89 of helpers to minimize boilerplate. See [`cargotest/mod.rs`] for an
90 introduction to writing tests.
91 * Make sure `cargo test` passes. If you do not have the cross-compilers
92 installed locally, install them using the instructions returned by
93 `cargo test cross_compile::cross_tests` (twice, with `--toolchain nightly`
94 added to get the nightly cross target too); alternatively just
95 ignore the cross-compile test failures or disable them by
96 using `CFG_DISABLE_CROSS_TESTS=1 cargo test`. Note that some tests are enabled
97 only on `nightly` toolchain. If you can, test both toolchains.
98 * All code changes are expected to comply with the formatting suggested by `rustfmt`.
99 You can use `rustup +stable component add rustfmt-preview` to install `rustfmt` and use
100 `rustfmt +stable --skip-children $FILE` on the changed files to automatically format your code.
101 * Push your commits to GitHub and create a pull request against Cargo's
106 After the pull request is made, a friendly bot will automatically assign a
107 reviewer; the review-process will make sure that the proposed changes are
108 sound. Please give the assigned reviewer sufficient time, especially during
109 weekends. If you don't get a reply, you may poke the core developers on [IRC].
111 A merge of Cargo's master-branch and your changes is immediately queued
112 to be tested after the pull request is made. In case unforeseen
113 problems are discovered during this step (e.g. a failure on a platform you
114 originally did not develop on), you may ask for guidance. Push additional
115 commits to your branch to tackle these problems.
117 The reviewer might point out changes deemed necessary. Please add them as
118 extra commits; this ensures that the reviewer can see what has changed since
119 the code was previously reviewed. Large or tricky changes may require several
120 passes of review and changes.
122 Once the reviewer approves your pull request, a friendly bot picks it up
123 and [merges][mergequeue] it into Cargo's `master` branch.
125 ## Contributing to the documentation
127 To contribute to the documentation, all you need to do is change the markdown
128 files in the `src/doc` directory. To view the rendered version of changes you
129 have made locally, make sure you have `mdbook` installed and run:
137 To install `mdbook` run `cargo install mdbook`.
142 Sometimes an issue will stay open, even though the bug has been fixed. And
143 sometimes, the original bug may go stale because something has changed in the
146 It can be helpful to go through older bug reports and make sure that they are
147 still valid. Load up an older issue, double check that it's still true, and
148 leave a comment letting us know if it is or is not. The [least recently
149 updated sort][lru] is good for finding issues like this.
151 Contributors with sufficient permissions on the Rust-repository can help by
152 adding labels to triage issues:
154 * Yellow, **A**-prefixed labels state which **area** of the project an issue
157 * Magenta, **B**-prefixed labels identify bugs which are **blockers**.
159 * Light purple, **C**-prefixed labels represent the **category** of an issue.
160 In particular, **C-feature-request** marks *proposals* for new features. If
161 an issue is **C-feature-request**, but is not **Feature accepted** or **I-nominated**,
162 then it was not thoroughly discussed, and might need some additional design
163 or perhaps should be implemented as an external subcommand first. Ping
164 @rust-lang/cargo if you want to send a PR for such issue.
166 * Dark purple, **Command**-prefixed labels mean the issue has to do with a
167 specific cargo command.
169 * Green, **E**-prefixed labels explain the level of **experience** or
170 **effort** necessary to fix the issue. [**E-mentor**][E-mentor] issues also
171 have some instructions on how to get started.
173 * Red, **I**-prefixed labels indicate the **importance** of the issue. The
174 **[I-nominated][]** label indicates that an issue has been nominated for
175 prioritizing at the next triage meeting.
177 * Purple gray, **O**-prefixed labels are the **operating system** or platform
178 that this issue is specific to.
180 * Orange, **P**-prefixed labels indicate a bug's **priority**. These labels
181 are only assigned during triage meetings and replace the **[I-nominated][]**
184 * The light orange **relnotes** label marks issues that should be documented in
185 the release notes of the next release.
188 [githelp]: https://dont-be-afraid-to-commit.readthedocs.io/en/latest/git/commandlinegit.html
189 [development-models]: https://help.github.com/articles/about-collaborative-development-models/
190 [gist]: https://gist.github.com/
191 [new-issues]: https://github.com/rust-lang/cargo/issues/new
192 [mergequeue]: https://buildbot2.rust-lang.org/homu/queue/cargo
193 [security policy]: https://www.rust-lang.org/security.html
194 [lru]: https://github.com/rust-lang/cargo/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-asc
195 [E-easy]: https://github.com/rust-lang/cargo/labels/E-easy
196 [E-mentor]: https://github.com/rust-lang/cargo/labels/E-mentor
197 [I-nominated]: https://github.com/rust-lang/cargo/labels/I-nominated
198 [Code of Conduct]: https://www.rust-lang.org/conduct.html
199 [IRC]: https://kiwiirc.com/client/irc.mozilla.org/cargo
200 [`cargotest/mod.rs`]: https://github.com/rust-lang/cargo/blob/master/tests/testsuite/cargotest/mod.rs
201 [irlo]: https://internals.rust-lang.org/
202 [subcommands]: https://doc.rust-lang.org/cargo/reference/external-tools.html#custom-subcommands