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 [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 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 ## Working on issues
  43
  44 If you're looking for somewhere to start, check out the [E-easy][E-Easy] and
  45 [E-mentor][E-mentor] tags.
  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, install them using the instructions returned by
  82 `cargo test cross_compile::cross_tests` (twice, with `--toolchain nightly`
  83 added to get the nightly cross target too); alternatively just
  84 ignore the cross-compile test failures or disable them by
  85 using `CFG_DISABLE_CROSS_TESTS=1 cargo test`. Note that some tests are enabled
  86 only on `nightly` toolchain. If you can, test both toolchains.
  87 * All code changes are expected to comply with the formatting suggested by `rustfmt`.
  88 You can use `rustup +stable component add rustfmt-preview` to install `rustfmt` and use
  89 `rustfmt +stable --skip-children $FILE` on the changed files to automatically format your code.
  90 * Push your commits to GitHub and create a pull request against Cargo's
  91 `master` branch.
  92
  93 ## Pull requests
  94
  95 After the pull request is made, a friendly bot will automatically assign a
  96 reviewer; the review-process will make sure that the proposed changes are
  97 sound. Please give the assigned reviewer sufficient time, especially during
  98 weekends. If you don't get a reply, you may poke the core developers on [IRC].
  99
 100 A merge of Cargo's master-branch and your changes is immediately queued
 101 to be tested after the pull request is made. In case unforeseen
 102 problems are discovered during this step (e.g. a failure on a platform you
 103 originally did not develop on), you may ask for guidance. Push additional
 104 commits to your branch to tackle these problems.
 105
 106 The reviewer might point out changes deemed necessary. Please add them as
 107 extra commits; this ensures that the reviewer can see what has changed since
 108 the code was previously reviewed. Large or tricky changes may require several
 109 passes of review and changes.
 110
 111 Once the reviewer approves your pull request, a friendly bot picks it up
 112 and [merges][mergequeue] it into Cargo's `master` branch.
 113
 114 ## Contributing to the documentation
 115
 116 To contribute to the documentation, all you need to do is change the markdown
 117 files in the `src/doc` directory. To view the rendered version of changes you
 118 have made locally, make sure you have `mdbook` installed and run:
 119
 120 ```sh
 121 cd src/doc
 122 mdbook build
 123 open book/index.html
 124 ```
 125
 126 To install `mdbook` run `cargo install mdbook`.
 127
 128
 129 ## Issue Triage
 130
 131 Sometimes an issue will stay open, even though the bug has been fixed. And
 132 sometimes, the original bug may go stale because something has changed in the
 133 meantime.
 134
 135 It can be helpful to go through older bug reports and make sure that they are
 136 still valid. Load up an older issue, double check that it's still true, and
 137 leave a comment letting us know if it is or is not. The [least recently
 138 updated sort][lru] is good for finding issues like this.
 139
 140 Contributors with sufficient permissions on the Rust-repository can help by
 141 adding labels to triage issues:
 142
 143 * Yellow, **A**-prefixed labels state which **area** of the project an issue
 144   relates to.
 145
 146 * Magenta, **B**-prefixed labels identify bugs which are **blockers**.
 147
 148 * Light purple, **C**-prefixed labels represent the **category** of an issue.
 149
 150 * Dark purple, **Command**-prefixed labels mean the issue has to do with a
 151   specific cargo command.
 152
 153 * Green, **E**-prefixed labels explain the level of **experience** or
 154   **effort** necessary to fix the issue. [**E-mentor**][E-mentor] issues also
 155   have some instructions on how to get started.
 156
 157 * Red, **I**-prefixed labels indicate the **importance** of the issue. The
 158   **[I-nominated][]** label indicates that an issue has been nominated for
 159   prioritizing at the next triage meeting.
 160
 161 * Purple gray, **O**-prefixed labels are the **operating system** or platform
 162   that this issue is specific to.
 163
 164 * Orange, **P**-prefixed labels indicate a bug's **priority**. These labels
 165   are only assigned during triage meetings and replace the **[I-nominated][]**
 166   label.
 167
 168 * The light orange **relnotes** label marks issues that should be documented in
 169   the release notes of the next release.
 170
 171
 172 [githelp]: https://dont-be-afraid-to-commit.readthedocs.io/en/latest/git/commandlinegit.html
 173 [development-models]: https://help.github.com/articles/about-collaborative-development-models/
 174 [gist]: https://gist.github.com/
 175 [new-issues]: https://github.com/rust-lang/cargo/issues/new
 176 [mergequeue]: https://buildbot2.rust-lang.org/homu/queue/cargo
 177 [security policy]: https://www.rust-lang.org/security.html
 178 [lru]: https://github.com/rust-lang/cargo/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-asc
 179 [E-easy]: https://github.com/rust-lang/cargo/labels/E-easy
 180 [E-mentor]: https://github.com/rust-lang/cargo/labels/E-mentor
 181 [I-nominated]: https://github.com/rust-lang/cargo/labels/I-nominated
 182 [Code of Conduct]: https://www.rust-lang.org/conduct.html
 183 [IRC]: https://kiwiirc.com/client/irc.mozilla.org/cargo