CONTRIBUTING.md

   1 # Contributing to Clippy
   2
   3 Hello fellow Rustacean! Great to see your interest in compiler internals and lints!
   4
   5 **First**: if you're unsure or afraid of _anything_, just ask or submit the issue or pull request anyway. You won't be yelled at for giving it your best effort. The worst that can happen is that you'll be politely asked to change something. We appreciate any sort of contributions, and don't want a wall of rules to get in the way of that.
   6
   7 Clippy welcomes contributions from everyone. There are many ways to contribute to Clippy and the following document explains how
   8 you can contribute and how to get started.
   9 If you have any questions about contributing or need help with anything, feel free to ask questions on issues or
  10 visit the `#clippy` IRC channel on `irc.mozilla.org` or meet us in `#wg-clippy` on [Discord](https://discord.gg/rust-lang).
  11
  12 All contributors are expected to follow the [Rust Code of Conduct](http://www.rust-lang.org/conduct.html).
  13
  14 * [Getting started](#getting-started)
  15   * [Finding something to fix/improve](#finding-something-to-fiximprove)
  16 * [Writing code](#writing-code)
  17   * [Author lint](#author-lint)
  18   * [Documentation](#documentation)
  19   * [Running test suite](#running-test-suite)
  20   * [Running rustfmt](#running-rustfmt)
  21   * [Testing manually](#testing-manually)
  22 * [How Clippy works](#how-clippy-works)
  23 * [Fixing nightly build failures](#fixing-build-failures-caused-by-rust)
  24 * [Issue and PR Triage](#issue-and-pr-triage)
  25 * [Bors and Homu](#bors-and-homu)
  26 * [Contributions](#contributions)
  27
  28 ## Getting started
  29
  30 High level approach:
  31
  32 1. Find something to fix/improve
  33 2. Change code (likely some file in `clippy_lints/src/`)
  34 3. Run `cargo test` in the root directory and wiggle code until it passes
  35 4. Open a PR (also can be done between 2. and 3. if you run into problems)
  36
  37 ### Finding something to fix/improve
  38
  39 All issues on Clippy are mentored, if you want help with a bug just ask @Manishearth, @llogiq, @mcarton or @oli-obk.
  40
  41 Some issues are easier than others. The [`good first issue`](https://github.com/rust-lang/rust-clippy/labels/good%20first%20issue)
  42 label can be used to find the easy issues. If you want to work on an issue, please leave a comment
  43 so that we can assign it to you!
  44
  45 There are also some abandoned PRs, marked with
  46 [`S-inactive-closed`](https://github.com/rust-lang/rust-clippy/pulls?q=is%3Aclosed+label%3AS-inactive-closed).
  47 Pretty often these PRs are nearly completed and just need some extra steps
  48 (formatting, addressing review comments, ...) to be merged. If you want to
  49 complete such a PR, please leave a comment in the PR and open a new one based
  50 on it.
  51
  52 Issues marked [`T-AST`](https://github.com/rust-lang/rust-clippy/labels/T-AST) involve simple
  53 matching of the syntax tree structure, and are generally easier than
  54 [`T-middle`](https://github.com/rust-lang/rust-clippy/labels/T-middle) issues, which involve types
  55 and resolved paths.
  56
  57 [`T-AST`](https://github.com/rust-lang/rust-clippy/labels/T-AST) issues will generally need you to match against a predefined syntax structure. To figure out
  58 how this syntax structure is encoded in the AST, it is recommended to run `rustc -Z ast-json` on an
  59 example of the structure and compare with the
  60 [nodes in the AST docs](https://doc.rust-lang.org/nightly/nightly-rustc/syntax/ast). Usually
  61 the lint will end up to be a nested series of matches and ifs,
  62 [like so](https://github.com/rust-lang/rust-clippy/blob/de5ccdfab68a5e37689f3c950ed1532ba9d652a0/src/misc.rs#L34).
  63
  64 [`E-medium`](https://github.com/rust-lang/rust-clippy/labels/E-medium) issues are generally
  65 pretty easy too, though it's recommended you work on an E-easy issue first. They are mostly classified
  66 as `E-medium`, since they might be somewhat involved code wise, but not difficult per-se.
  67
  68 [`T-middle`](https://github.com/rust-lang/rust-clippy/labels/T-middle) issues can
  69 be more involved and require verifying types. The
  70 [`ty`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc/ty) module contains a
  71 lot of methods that are useful, though one of the most useful would be `expr_ty` (gives the type of
  72 an AST expression). `match_def_path()` in Clippy's `utils` module can also be useful.
  73
  74 ## Writing code
  75
  76 Clippy depends on the current git master version of rustc, which can change rapidly. Make sure you're
  77 working near rust-clippy's master, and use the `setup-toolchain.sh` script to configure the appropriate
  78 toolchain for this directory.
  79
  80 [Llogiq's blog post on lints](https://llogiq.github.io/2015/06/04/workflows.html) is a nice primer
  81 to lint-writing, though it does get into advanced stuff. Most lints consist of an implementation of
  82 `LintPass` with one or more of its default methods overridden. See the existing lints for examples
  83 of this.
  84
  85 If you want to add a new lint or change existing ones apart from bugfixing, it's
  86 also a good idea to give the [stability guarantees][rfc_stability] and
  87 [lint categories][rfc_lint_cats] sections of the [Clippy 1.0 RFC][clippy_rfc] a
  88 quick read.
  89
  90 ### Author lint
  91
  92 There is also the internal `author` lint to generate Clippy code that detects the offending pattern. It does not work for all of the Rust syntax, but can give a good starting point.
  93
  94 First, create a new UI test file in the `tests/ui/` directory with the pattern you want to match:
  95
  96 ```rust
  97 // ./tests/ui/my_lint.rs
  98 fn main() {
  99     #[clippy::author]
 100     let arr: [i32; 1] = [7]; // Replace line with the code you want to match
 101 }
 102 ```
 103
 104 Now you run `TESTNAME=ui/my_lint cargo uitest` to produce
 105 a `.stdout` file with the generated code:
 106
 107 ```rust
 108 // ./tests/ui/my_lint.stdout
 109
 110 if_chain! {
 111     if let ExprKind::Array(ref elements) = stmt.node;
 112     if elements.len() == 1;
 113     if let ExprKind::Lit(ref lit) = elements[0].node;
 114     if let LitKind::Int(7, _) = lit.node;
 115     then {
 116         // report your lint here
 117     }
 118 }
 119 ```
 120
 121 If the command was executed successfully, you can copy the code over to where you are implementing your lint.
 122
 123 ### Documentation
 124
 125 Please document your lint with a doc comment akin to the following:
 126
 127 ```rust
 128 /// **What it does:** Checks for ... (describe what the lint matches).
 129 ///
 130 /// **Why is this bad?** Supply the reason for linting the code.
 131 ///
 132 /// **Known problems:** None. (Or describe where it could go wrong.)
 133 ///
 134 /// **Example:**
 135 ///
 136 /// ```rust
 137 /// // Bad
 138 /// Insert a short example of code that triggers the lint
 139 ///
 140 /// // Good
 141 /// Insert a short example of improved code that doesn't trigger the lint
 142 /// ```
 143 ```
 144
 145 Once your lint is merged it will show up in the [lint list](https://rust-lang.github.io/rust-clippy/master/index.html)
 146
 147 ### Running test suite
 148
 149 Use `cargo test` to run the whole testsuite.
 150
 151 If you don't want to wait for all tests to finish, you can also execute a single test file by using `TESTNAME` to specify the test to run:
 152
 153 ```bash
 154 TESTNAME=ui/empty_line_after_outer_attr cargo uitest
 155 ```
 156
 157 Clippy uses UI tests. UI tests check that the output of the compiler is exactly as expected.
 158 Of course there's little sense in writing the output yourself or copying it around.
 159 Therefore you should use `tests/ui/update-all-references.sh` (after running
 160 `cargo test`) and check whether the output looks as you expect with `git diff`. Commit all
 161 `*.stderr` files, too.
 162
 163 If the lint you are working on is making use of structured suggestions, the
 164 test file should include a `// run-rustfix` comment at the top. This will
 165 additionally run [rustfix](https://github.com/rust-lang-nursery/rustfix) for
 166 that test. Rustfix will apply the suggestions from the lint to the code of the
 167 test file and compare that to the contents of a `.fixed` file.
 168
 169 Use `tests/ui/update-all-references.sh` to automatically generate the
 170 `.fixed` file after running `cargo test`.
 171
 172 ### Running rustfmt
 173
 174 [Rustfmt](https://github.com/rust-lang/rustfmt) is a tool for formatting Rust code according
 175 to style guidelines. The code has to be formatted by `rustfmt` before a PR will be merged.
 176
 177 It can be installed via `rustup`:
 178 ```bash
 179 rustup component add rustfmt
 180 ```
 181
 182 Use `cargo fmt --all` to format the whole codebase.
 183
 184 ### Testing manually
 185
 186 Manually testing against an example file is useful if you have added some
 187 `println!`s and test suite output becomes unreadable.  To try Clippy with your
 188 local modifications, run `env CLIPPY_TESTS=true cargo run --bin clippy-driver -- -L ./target/debug input.rs`
 189 from the working copy root.
 190
 191 ## How Clippy works
 192
 193 Clippy is a [rustc compiler plugin][compiler_plugin]. The main entry point is at [`src/lib.rs`][main_entry]. In there, the lint registration is delegated to the [`clippy_lints`][lint_crate] crate.
 194
 195 [`clippy_lints/src/lib.rs`][lint_crate_entry] imports all the different lint modules and registers them with the rustc plugin registry. For example, the [`else_if_without_else`][else_if_without_else] lint is registered like this:
 196
 197 ```rust
 198 // ./clippy_lints/src/lib.rs
 199
 200 // ...
 201 pub mod else_if_without_else;
 202 // ...
 203
 204 pub fn register_plugins(reg: &mut rustc_plugin::Registry) {
 205     // ...
 206     reg.register_early_lint_pass(box else_if_without_else::ElseIfWithoutElse);
 207     // ...
 208
 209     reg.register_lint_group("clippy::restriction", vec![
 210         // ...
 211         else_if_without_else::ELSE_IF_WITHOUT_ELSE,
 212         // ...
 213     ]);
 214 }
 215 ```
 216
 217 The [`rustc_plugin::PluginRegistry`][plugin_registry] provides two methods to register lints: [register_early_lint_pass][reg_early_lint_pass] and [register_late_lint_pass][reg_late_lint_pass].
 218 Both take an object that implements an [`EarlyLintPass`][early_lint_pass] or [`LateLintPass`][late_lint_pass] respectively. This is done in every single lint.
 219 It's worth noting that the majority of `clippy_lints/src/lib.rs` is autogenerated by `util/dev update_lints` and you don't have to add anything by hand. When you are writing your own lint, you can use that script to save you some time.
 220
 221 ```rust
 222 // ./clippy_lints/src/else_if_without_else.rs
 223
 224 use rustc::lint::{EarlyLintPass, LintArray, LintPass};
 225
 226 // ...
 227
 228 pub struct ElseIfWithoutElse;
 229
 230 // ...
 231
 232 impl EarlyLintPass for ElseIfWithoutElse {
 233     // ... the functions needed, to make the lint work
 234 }
 235 ```
 236
 237 The difference between `EarlyLintPass` and `LateLintPass` is that the methods of the `EarlyLintPass` trait only provide AST information. The methods of the `LateLintPass` trait are executed after type checking and contain type information via the `LateContext` parameter.
 238
 239 That's why the `else_if_without_else` example uses the `register_early_lint_pass` function. Because the [actual lint logic][else_if_without_else] does not depend on any type information.
 240
 241 ## Fixing build failures caused by Rust
 242
 243 Clippy will sometimes fail to build from source because building it depends on unstable internal Rust features. Most of the times we have to adapt to the changes and only very rarely there's an actual bug in Rust. Fixing build failures caused by Rust updates, can be a good way to learn about Rust internals.
 244
 245 In order to find out why Clippy does not work properly with a new Rust commit, you can use the [rust-toolstate commit history][toolstate_commit_history].
 246 You will then have to look for the last commit that contains `test-pass -> build-fail` or `test-pass` -> `test-fail` for the `clippy-driver` component. [Here][toolstate_commit] is an example.
 247
 248 The commit message contains a link to the PR. The PRs are usually small enough to discover the breaking API change and if they are bigger, they likely include some discussion that may help you to fix Clippy.
 249
 250 To check if Clippy is available for a specific target platform, you can check
 251 the [rustup component history][rustup_component_history].
 252
 253 If you decide to make Clippy work again with a Rust commit that breaks it,
 254 you probably want to install the latest Rust from master locally and run Clippy
 255 using that version of Rust.
 256
 257 You can use [rustup-toolchain-install-master][rtim] to do that:
 258
 259 ```
 260 cargo install rustup-toolchain-install-master
 261 rustup-toolchain-install-master -n master --force
 262 rustup override set master
 263 cargo test
 264 ```
 265
 266 ## Issue and PR triage
 267
 268 Clippy is following the [Rust triage procedure][triage] for issues and pull
 269 requests.
 270
 271 However, we are a smaller project with all contributors being volunteers
 272 currently. Between writing new lints, fixing issues, reviewing pull requests and
 273 responding to issues there may not always be enough time to stay on top of it
 274 all.
 275
 276 Our highest priority is fixing [crashes][l-crash] and [bugs][l-bug]. We don't
 277 want Clippy to crash on your code and we want it to be as reliable as the
 278 suggestions from Rust compiler errors.
 279
 280 ## Bors and Homu
 281
 282 We use a bot powered by [Homu][homu] to help automate testing and landing of pull
 283 requests in Clippy. The bot's username is @bors.
 284
 285 You can find the Clippy bors queue [here][homu_queue].
 286
 287 If you have @bors permissions, you can find an overview of the available
 288 commands [here][homu_instructions].
 289
 290
 291 ## Contributions
 292
 293 Contributions to Clippy should be made in the form of GitHub pull requests. Each pull request will
 294 be reviewed by a core contributor (someone with permission to land patches) and either landed in the
 295 main tree or given feedback for changes that would be required.
 296
 297 All code in this repository is under the [Apache-2.0](http://www.apache.org/licenses/LICENSE-2.0>)
 298 or the [MIT](http://opensource.org/licenses/MIT) license.
 299
 300 <!-- adapted from https://github.com/servo/servo/blob/master/CONTRIBUTING.md -->
 301
 302 [main_entry]: https://github.com/rust-lang/rust-clippy/blob/c5b39a5917ffc0f1349b6e414fa3b874fdcf8429/src/lib.rs#L14
 303 [lint_crate]: https://github.com/rust-lang/rust-clippy/tree/c5b39a5917ffc0f1349b6e414fa3b874fdcf8429/clippy_lints/src
 304 [lint_crate_entry]: https://github.com/rust-lang/rust-clippy/blob/c5b39a5917ffc0f1349b6e414fa3b874fdcf8429/clippy_lints/src/lib.rs
 305 [else_if_without_else]: https://github.com/rust-lang/rust-clippy/blob/c5b39a5917ffc0f1349b6e414fa3b874fdcf8429/clippy_lints/src/else_if_without_else.rs
 306 [compiler_plugin]: https://doc.rust-lang.org/unstable-book/language-features/plugin.html#lint-plugins
 307 [plugin_registry]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_plugin/registry/struct.Registry.html
 308 [reg_early_lint_pass]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_plugin/registry/struct.Registry.html#method.register_early_lint_pass
 309 [reg_late_lint_pass]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_plugin/registry/struct.Registry.html#method.register_late_lint_pass
 310 [early_lint_pass]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc/lint/trait.EarlyLintPass.html
 311 [late_lint_pass]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc/lint/trait.LateLintPass.html
 312 [toolstate_commit_history]: https://github.com/rust-lang-nursery/rust-toolstate/commits/master
 313 [toolstate_commit]: https://github.com/rust-lang-nursery/rust-toolstate/commit/6ce0459f6bfa7c528ae1886492a3e0b5ef0ee547
 314 [rtim]: https://github.com/kennytm/rustup-toolchain-install-master
 315 [rustup_component_history]: https://mexus.github.io/rustup-components-history
 316 [clippy_rfc]: https://github.com/rust-lang/rfcs/blob/master/text/2476-clippy-uno.md
 317 [rfc_stability]: https://github.com/rust-lang/rfcs/blob/master/text/2476-clippy-uno.md#stability-guarantees
 318 [rfc_lint_cats]: https://github.com/rust-lang/rfcs/blob/master/text/2476-clippy-uno.md#lint-audit-and-categories
 319 [triage]: https://forge.rust-lang.org/triage-procedure.html
 320 [l-crash]: https://github.com/rust-lang/rust-clippy/labels/L-crash%20%3Aboom%3A
 321 [l-bug]: https://github.com/rust-lang/rust-clippy/labels/L-bug%20%3Abeetle%3A
 322 [homu]: https://github.com/servo/homu
 323 [homu_instructions]: https://buildbot2.rust-lang.org/homu/
 324 [homu_queue]: https://buildbot2.rust-lang.org/homu/queue/clippy