|
| 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, run: |
| 113 | + |
| 114 | +```sh |
| 115 | +sh src/ci/dox.sh |
| 116 | +open target/doc/index.html |
| 117 | +``` |
| 118 | + |
| 119 | + |
| 120 | +## Issue Triage |
| 121 | + |
| 122 | +Sometimes an issue will stay open, even though the bug has been fixed. And |
| 123 | +sometimes, the original bug may go stale because something has changed in the |
| 124 | +meantime. |
| 125 | + |
| 126 | +It can be helpful to go through older bug reports and make sure that they are |
| 127 | +still valid. Load up an older issue, double check that it's still true, and |
| 128 | +leave a comment letting us know if it is or is not. The [least recently |
| 129 | +updated sort][lru] is good for finding issues like this. |
| 130 | + |
| 131 | +Contributors with sufficient permissions on the Rust-repository can help by |
| 132 | +adding labels to triage issues: |
| 133 | + |
| 134 | +* Yellow, **A**-prefixed labels state which **area** of the project an issue |
| 135 | + relates to. |
| 136 | + |
| 137 | +* Magenta, **B**-prefixed labels identify bugs which are **blockers**. |
| 138 | + |
| 139 | +* Light purple, **C**-prefixed labels represent the **category** of an issue. |
| 140 | + |
| 141 | +* Dark purple, **Command**-prefixed labels mean the issue has to do with a |
| 142 | + specific cargo command. |
| 143 | + |
| 144 | +* Green, **E**-prefixed labels explain the level of **experience** or |
| 145 | + **effort** necessary to fix the issue. [**E-mentor**][E-mentor] issues also |
| 146 | + have some instructions on how to get started. |
| 147 | + |
| 148 | +* Red, **I**-prefixed labels indicate the **importance** of the issue. The |
| 149 | + [I-nominated][inom] label indicates that an issue has been nominated for |
| 150 | + prioritizing at the next triage meeting. |
| 151 | + |
| 152 | +* Purple gray, **O**-prefixed labels are the **operating system** or platform |
| 153 | + that this issue is specific to. |
| 154 | + |
| 155 | +* Orange, **P**-prefixed labels indicate a bug's **priority**. These labels |
| 156 | + are only assigned during triage meetings and replace the [I-nominated][inom] |
| 157 | + label. |
| 158 | + |
| 159 | +* The light orange **relnotes** label marks issues that should be documented in |
| 160 | + the release notes of the next release. |
| 161 | + |
| 162 | + |
| 163 | +[githelp]: https://dont-be-afraid-to-commit.readthedocs.io/en/latest/git/commandlinegit.html |
| 164 | +[development-models]: https://help.github.com/articles/about-collaborative-development-models/ |
| 165 | +[gist]: https://gist.github.com/ |
| 166 | +[new-issues]: https://github.com/rust-lang/cargo/issues/new |
| 167 | +[mergequeue]: https://buildbot2.rust-lang.org/homu/queue/cargo |
| 168 | +[security policy]: https://www.rust-lang.org/security.html |
| 169 | +[lru]: https://github.com/rust-lang/cargo/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-asc |
| 170 | +[E-easy]: https://github.com/rust-lang/cargo/labels/E-easy |
| 171 | +[E-mentor]: https://github.com/rust-lang/cargo/labels/E-mentor |
| 172 | +[Code of Conduct]: https://www.rust-lang.org/conduct.html |
| 173 | +[IRC]: https://kiwiirc.com/client/irc.mozilla.org/cargo |
0 commit comments