]>
Commit | Line | Data |
---|---|---|
d11a429d AK |
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 | |
47faa0f1 | 5 | describes the high-level structure of Cargo and [E-easy] bugs on the |
d11a429d AK |
6 | issue tracker. |
7 | ||
47faa0f1 LL |
8 | If you have a general question about Cargo or it's internals, feel free to ask |
9 | on [IRC]. | |
d11a429d | 10 | |
47faa0f1 LL |
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 | ||
139c7503 EH |
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 | |
506786d0 | 27 | necessary to use it exactly: |
47faa0f1 LL |
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. | |
d11a429d | 41 | |
9bed341d AK |
42 | |
43 | ## Feature requests | |
44 | ||
45 | Cargo follows the general Rust model of evolution. All major features go through | |
d3f118d4 DW |
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. | |
9bed341d | 51 | |
47faa0f1 | 52 | ## Working on issues |
d11a429d | 53 | |
139c7503 | 54 | If you're looking for somewhere to start, check out the [E-easy][E-Easy] and |
506786d0 | 55 | [E-mentor][E-mentor] tags. |
d11a429d | 56 | |
47faa0f1 LL |
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. | |
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 crate `cargotest` provides a vast amount | |
139c7503 EH |
89 | of helpers to minimize boilerplate. See [`cargotest/mod.rs`] for an |
90 | introduction to writing tests. | |
47faa0f1 | 91 | * Make sure `cargo test` passes. If you do not have the cross-compilers |
e21f5b41 DW |
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 | |
d11a429d | 96 | using `CFG_DISABLE_CROSS_TESTS=1 cargo test`. Note that some tests are enabled |
47faa0f1 | 97 | only on `nightly` toolchain. If you can, test both toolchains. |
87770aee | 98 | * All code changes are expected to comply with the formatting suggested by `rustfmt`. |
ad5610fe DW |
99 | You can use `rustup component add --toolchain nightly rustfmt-preview` to install `rustfmt` and use |
100 | `rustfmt +nightly --unstable-features --skip-children` on the changed files to automatically format your code. | |
47faa0f1 LL |
101 | * Push your commits to GitHub and create a pull request against Cargo's |
102 | `master` branch. | |
103 | ||
104 | ## Pull requests | |
105 | ||
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]. | |
d11a429d | 110 | |
47faa0f1 LL |
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. | |
100877b4 | 116 | |
47faa0f1 LL |
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. | |
d11a429d | 121 | |
47faa0f1 LL |
122 | Once the reviewer approves your pull request, a friendly bot picks it up |
123 | and [merges][mergequeue] it into Cargo's `master` branch. | |
d11a429d | 124 | |
47faa0f1 LL |
125 | ## Contributing to the documentation |
126 | ||
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 | |
e59171aa | 129 | have made locally, make sure you have `mdbook` installed and run: |
d11a429d AK |
130 | |
131 | ```sh | |
e59171aa DG |
132 | cd src/doc |
133 | mdbook build | |
134 | open book/index.html | |
d11a429d AK |
135 | ``` |
136 | ||
e59171aa DG |
137 | To install `mdbook` run `cargo install mdbook`. |
138 | ||
d11a429d | 139 | |
3bfc2ca2 CNG |
140 | ## Issue Triage |
141 | ||
47faa0f1 | 142 | Sometimes an issue will stay open, even though the bug has been fixed. And |
3bfc2ca2 CNG |
143 | sometimes, the original bug may go stale because something has changed in the |
144 | meantime. | |
145 | ||
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. | |
150 | ||
47faa0f1 LL |
151 | Contributors with sufficient permissions on the Rust-repository can help by |
152 | adding labels to triage issues: | |
3bfc2ca2 CNG |
153 | |
154 | * Yellow, **A**-prefixed labels state which **area** of the project an issue | |
155 | relates to. | |
156 | ||
157 | * Magenta, **B**-prefixed labels identify bugs which are **blockers**. | |
158 | ||
159 | * Light purple, **C**-prefixed labels represent the **category** of an issue. | |
986d78d7 AK |
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. | |
3bfc2ca2 CNG |
165 | |
166 | * Dark purple, **Command**-prefixed labels mean the issue has to do with a | |
167 | specific cargo command. | |
168 | ||
169 | * Green, **E**-prefixed labels explain the level of **experience** or | |
a9977f3c AK |
170 | **effort** necessary to fix the issue. [**E-mentor**][E-mentor] issues also |
171 | have some instructions on how to get started. | |
3bfc2ca2 CNG |
172 | |
173 | * Red, **I**-prefixed labels indicate the **importance** of the issue. The | |
463f207a | 174 | **[I-nominated][]** label indicates that an issue has been nominated for |
3bfc2ca2 CNG |
175 | prioritizing at the next triage meeting. |
176 | ||
177 | * Purple gray, **O**-prefixed labels are the **operating system** or platform | |
178 | that this issue is specific to. | |
179 | ||
180 | * Orange, **P**-prefixed labels indicate a bug's **priority**. These labels | |
463f207a | 181 | are only assigned during triage meetings and replace the **[I-nominated][]** |
3bfc2ca2 CNG |
182 | label. |
183 | ||
0cfe6355 CNG |
184 | * The light orange **relnotes** label marks issues that should be documented in |
185 | the release notes of the next release. | |
186 | ||
3bfc2ca2 | 187 | |
47faa0f1 LL |
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 | |
3bfc2ca2 | 194 | [lru]: https://github.com/rust-lang/cargo/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-asc |
47faa0f1 | 195 | [E-easy]: https://github.com/rust-lang/cargo/labels/E-easy |
a9977f3c | 196 | [E-mentor]: https://github.com/rust-lang/cargo/labels/E-mentor |
463f207a | 197 | [I-nominated]: https://github.com/rust-lang/cargo/labels/I-nominated |
47faa0f1 | 198 | [Code of Conduct]: https://www.rust-lang.org/conduct.html |
d11a429d | 199 | [IRC]: https://kiwiirc.com/client/irc.mozilla.org/cargo |
139c7503 | 200 | [`cargotest/mod.rs`]: https://github.com/rust-lang/cargo/blob/master/tests/testsuite/cargotest/mod.rs |
9bed341d AK |
201 | [irlo]: https://internals.rust-lang.org/ |
202 | [subcommands]: https://doc.rust-lang.org/cargo/reference/external-tools.html#custom-subcommands |