]>
Commit | Line | Data |
---|---|---|
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 [IRC]. | |
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 | |
26 | link][new-issues] and filling out the fields. | |
27 | Here's a template that you can use to file an issue, though it's not necessary to | |
28 | use it exactly: | |
29 | ||
30 | <short summary of the problem> | |
31 | ||
32 | I tried this: <minimal example that causes the problem> | |
33 | ||
34 | I expected to see this happen: <explanation> | |
35 | ||
36 | Instead, this happened: <explanation> | |
37 | ||
38 | I'm using <output of `cargo --version`> | |
39 | ||
40 | All three components are important: what you did, what you expected, what | |
41 | happened instead. Please use https://gist.github.com/ if your examples run long. | |
42 | ||
43 | ## Working on issues | |
44 | ||
45 | If you're looking for somewhere to start, check out the [E-easy][E-Easy] tag. | |
46 | ||
47 | Feel free to ask for guidelines on how to tackle a problem on [IRC] or open a | |
48 | [new issue][new-issues]. This is especially important if you want to add new | |
49 | features to Cargo or make large changes to the already existing code-base. | |
50 | Cargo's core developers will do their best to provide help. | |
51 | ||
52 | If you start working on an already-filed issue, post a comment on this issue to | |
53 | let people know that somebody is working it. Feel free to ask for comments if | |
54 | you are unsure about the solution you would like to submit. | |
55 | ||
56 | While Cargo does make use of some Rust-features available only through the | |
57 | `nightly` toolchain, it must compile on stable Rust. Code added to Cargo | |
58 | is encouraged to make use of the latest stable features of the language and | |
59 | `stdlib`. | |
60 | ||
61 | We use the "fork and pull" model [described here][development-models], where | |
62 | contributors push changes to their personal fork and create pull requests to | |
63 | bring those changes into the source repository. This process is partly | |
64 | automated: Pull requests are made against Cargo's master-branch, tested and | |
65 | reviewed. Once a change is approved to be merged, a friendly bot merges the | |
66 | changes into an internal branch, runs the full test-suite on that branch | |
67 | and only then merges into master. This ensures that Cargo's master branch | |
68 | passes the test-suite at all times. | |
69 | ||
70 | Your basic steps to get going: | |
71 | ||
72 | * Fork Cargo and create a branch from master for the issue you are working on. | |
73 | * Please adhere to the code style that you see around the location you are | |
74 | working on. | |
75 | * [Commit as you go][githelp]. | |
76 | * Include tests that cover all non-trivial code. The existing tests | |
77 | in `test/` provide templates on how to test Cargo's behavior in a | |
78 | sandbox-environment. The internal crate `cargotest` provides a vast amount | |
79 | of helpers to minimize boilerplate. | |
80 | * Make sure `cargo test` passes. If you do not have the cross-compilers | |
81 | installed locally, ignore the cross-compile test failures or disable them by | |
82 | using `CFG_DISABLE_CROSS_TESTS=1 cargo test`. Note that some tests are enabled | |
83 | only on `nightly` toolchain. If you can, test both toolchains. | |
84 | * Push your commits to GitHub and create a pull request against Cargo's | |
85 | `master` branch. | |
86 | ||
87 | ## Pull requests | |
88 | ||
89 | After the pull request is made, a friendly bot will automatically assign a | |
90 | reviewer; the review-process will make sure that the proposed changes are | |
91 | sound. Please give the assigned reviewer sufficient time, especially during | |
92 | weekends. If you don't get a reply, you may poke the core developers on [IRC]. | |
93 | ||
94 | A merge of Cargo's master-branch and your changes is immediately queued | |
95 | to be tested after the pull request is made. In case unforeseen | |
96 | problems are discovered during this step (e.g. a failure on a platform you | |
97 | originally did not develop on), you may ask for guidance. Push additional | |
98 | commits to your branch to tackle these problems. | |
99 | ||
100 | The reviewer might point out changes deemed necessary. Please add them as | |
101 | extra commits; this ensures that the reviewer can see what has changed since | |
102 | the code was previously reviewed. Large or tricky changes may require several | |
103 | passes of review and changes. | |
104 | ||
105 | Once the reviewer approves your pull request, a friendly bot picks it up | |
106 | and [merges][mergequeue] it into Cargo's `master` branch. | |
107 | ||
108 | ## Contributing to the documentation | |
109 | ||
110 | To contribute to the documentation, all you need to do is change the markdown | |
111 | files in the `src/doc` directory. To view the rendered version of changes you | |
112 | have made locally, make sure you have `mdbook` installed and run: | |
113 | ||
114 | ```sh | |
115 | cd src/doc | |
116 | mdbook build | |
117 | open book/index.html | |
118 | ``` | |
119 | ||
120 | To install `mdbook` run `cargo install mdbook`. | |
121 | ||
122 | ||
123 | ## Issue Triage | |
124 | ||
125 | Sometimes an issue will stay open, even though the bug has been fixed. And | |
126 | sometimes, the original bug may go stale because something has changed in the | |
127 | meantime. | |
128 | ||
129 | It can be helpful to go through older bug reports and make sure that they are | |
130 | still valid. Load up an older issue, double check that it's still true, and | |
131 | leave a comment letting us know if it is or is not. The [least recently | |
132 | updated sort][lru] is good for finding issues like this. | |
133 | ||
134 | Contributors with sufficient permissions on the Rust-repository can help by | |
135 | adding labels to triage issues: | |
136 | ||
137 | * Yellow, **A**-prefixed labels state which **area** of the project an issue | |
138 | relates to. | |
139 | ||
140 | * Magenta, **B**-prefixed labels identify bugs which are **blockers**. | |
141 | ||
142 | * Light purple, **C**-prefixed labels represent the **category** of an issue. | |
143 | ||
144 | * Dark purple, **Command**-prefixed labels mean the issue has to do with a | |
145 | specific cargo command. | |
146 | ||
147 | * Green, **E**-prefixed labels explain the level of **experience** or | |
148 | **effort** necessary to fix the issue. [**E-mentor**][E-mentor] issues also | |
149 | have some instructions on how to get started. | |
150 | ||
151 | * Red, **I**-prefixed labels indicate the **importance** of the issue. The | |
152 | [I-nominated][inom] label indicates that an issue has been nominated for | |
153 | prioritizing at the next triage meeting. | |
154 | ||
155 | * Purple gray, **O**-prefixed labels are the **operating system** or platform | |
156 | that this issue is specific to. | |
157 | ||
158 | * Orange, **P**-prefixed labels indicate a bug's **priority**. These labels | |
159 | are only assigned during triage meetings and replace the [I-nominated][inom] | |
160 | label. | |
161 | ||
162 | * The light orange **relnotes** label marks issues that should be documented in | |
163 | the release notes of the next release. | |
164 | ||
165 | ||
166 | [githelp]: https://dont-be-afraid-to-commit.readthedocs.io/en/latest/git/commandlinegit.html | |
167 | [development-models]: https://help.github.com/articles/about-collaborative-development-models/ | |
168 | [gist]: https://gist.github.com/ | |
169 | [new-issues]: https://github.com/rust-lang/cargo/issues/new | |
170 | [mergequeue]: https://buildbot2.rust-lang.org/homu/queue/cargo | |
171 | [security policy]: https://www.rust-lang.org/security.html | |
172 | [lru]: https://github.com/rust-lang/cargo/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-asc | |
173 | [E-easy]: https://github.com/rust-lang/cargo/labels/E-easy | |
174 | [E-mentor]: https://github.com/rust-lang/cargo/labels/E-mentor | |
175 | [Code of Conduct]: https://www.rust-lang.org/conduct.html | |
176 | [IRC]: https://kiwiirc.com/client/irc.mozilla.org/cargo |