1 # Contributing to Clippy
3 Hello fellow Rustacean! Great to see your interest in compiler internals and lints!
5 **First**: if you're unsure or afraid of _anything_, just ask or submit the issue or pull request anyway. You won't be
6 yelled at for giving it your best effort. The worst that can happen is that you'll be politely asked to change
7 something. We appreciate any sort of contributions, and don't want a wall of rules to get in the way of that.
9 Clippy welcomes contributions from everyone. There are many ways to contribute to Clippy and the following document
10 explains how you can contribute and how to get started. If you have any questions about contributing or need help with
11 anything, feel free to ask questions on issues or visit the `#clippy` on [Zulip].
13 All contributors are expected to follow the [Rust Code of Conduct].
15 - [Contributing to Clippy](#contributing-to-clippy)
16 - [The Clippy book](#the-clippy-book)
17 - [High level approach](#high-level-approach)
18 - [Finding something to fix/improve](#finding-something-to-fiximprove)
19 - [Writing code](#writing-code)
20 - [Getting code-completion for rustc internals to work](#getting-code-completion-for-rustc-internals-to-work)
21 - [IntelliJ Rust](#intellij-rust)
22 - [Rust Analyzer](#rust-analyzer)
23 - [How Clippy works](#how-clippy-works)
24 - [Issue and PR triage](#issue-and-pr-triage)
25 - [Bors and Homu](#bors-and-homu)
26 - [Contributions](#contributions)
28 [Zulip]: https://rust-lang.zulipchat.com/#narrow/stream/clippy
29 [Rust Code of Conduct]: https://www.rust-lang.org/policies/code-of-conduct
33 If you're new to Clippy and don't know where to start the [Clippy book] includes
34 a developer guide and is a good place to start your journey.
36 <!-- FIXME: Link to the deployed book, once it is deployed through CI -->
37 [Clippy book]: book/src
39 ## High level approach
41 1. Find something to fix/improve
42 2. Change code (likely some file in `clippy_lints/src/`)
43 3. Follow the instructions in the [Basics docs](book/src/development/basics.md)
45 4. Run `cargo test` in the root directory and wiggle code until it passes
46 5. Open a PR (also can be done after 2. if you run into problems)
48 ## Finding something to fix/improve
50 All issues on Clippy are mentored, if you want help simply ask someone from the
51 Clippy team directly by mentioning them in the issue or over on [Zulip]. All
52 currently active team members can be found
53 [here](https://github.com/rust-lang/highfive/blob/master/highfive/configs/rust-lang/rust-clippy.json#L3)
55 Some issues are easier than others. The [`good-first-issue`] label can be used to find the easy
56 issues. You can use `@rustbot claim` to assign the issue to yourself.
58 There are also some abandoned PRs, marked with [`S-inactive-closed`].
59 Pretty often these PRs are nearly completed and just need some extra steps
60 (formatting, addressing review comments, ...) to be merged. If you want to
61 complete such a PR, please leave a comment in the PR and open a new one based
64 Issues marked [`T-AST`] involve simple matching of the syntax tree structure,
65 and are generally easier than [`T-middle`] issues, which involve types
68 [`T-AST`] issues will generally need you to match against a predefined syntax structure.
69 To figure out how this syntax structure is encoded in the AST, it is recommended to run
70 `rustc -Z unpretty=ast-tree` on an example of the structure and compare with the [nodes in the AST docs].
71 Usually the lint will end up to be a nested series of matches and ifs, [like so][deep-nesting].
72 But we can make it nest-less by using [let chains], [like this][nest-less].
74 [`E-medium`] issues are generally pretty easy too, though it's recommended you work on an [`good-first-issue`]
75 first. Sometimes they are only somewhat involved code wise, but not difficult per-se.
76 Note that [`E-medium`] issues may require some knowledge of Clippy internals or some
77 debugging to find the actual problem behind the issue.
79 [`T-middle`] issues can be more involved and require verifying types. The [`ty`] module contains a
80 lot of methods that are useful, though one of the most useful would be `expr_ty` (gives the type of
81 an AST expression). `match_def_path()` in Clippy's `utils` module can also be useful.
83 [`good-first-issue`]: https://github.com/rust-lang/rust-clippy/labels/good-first-issue
84 [`S-inactive-closed`]: https://github.com/rust-lang/rust-clippy/pulls?q=is%3Aclosed+label%3AS-inactive-closed
85 [`T-AST`]: https://github.com/rust-lang/rust-clippy/labels/T-AST
86 [`T-middle`]: https://github.com/rust-lang/rust-clippy/labels/T-middle
87 [`E-medium`]: https://github.com/rust-lang/rust-clippy/labels/E-medium
88 [`ty`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty
89 [nodes in the AST docs]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_ast/ast/
90 [deep-nesting]: https://github.com/rust-lang/rust-clippy/blob/5e4f0922911536f80d9591180fa604229ac13939/clippy_lints/src/mem_forget.rs#L31-L45
91 [let chains]: https://github.com/rust-lang/rust/pull/94927
92 [nest-less]: https://github.com/rust-lang/rust-clippy/blob/5e4f0922911536f80d9591180fa604229ac13939/clippy_lints/src/bit_mask.rs#L133-L159
94 ## Getting code-completion for rustc internals to work
97 Unfortunately, [`IntelliJ Rust`][IntelliJ_rust_homepage] does not (yet?) understand how Clippy uses compiler-internals
98 using `extern crate` and it also needs to be able to read the source files of the rustc-compiler which are not
99 available via a `rustup` component at the time of writing.
100 To work around this, you need to have a copy of the [rustc-repo][rustc_repo] available which can be obtained via
101 `git clone https://github.com/rust-lang/rust/`.
102 Then you can run a `cargo dev` command to automatically make Clippy use the rustc-repo via path-dependencies
103 which `IntelliJ Rust` will be able to understand.
104 Run `cargo dev setup intellij --repo-path <repo-path>` where `<repo-path>` is a path to the rustc repo
106 The command will add path-dependencies pointing towards rustc-crates inside the rustc repo to
107 Clippy's `Cargo.toml`s and should allow `IntelliJ Rust` to understand most of the types that Clippy uses.
108 Just make sure to remove the dependencies again before finally making a pull request!
110 [rustc_repo]: https://github.com/rust-lang/rust/
111 [IntelliJ_rust_homepage]: https://intellij-rust.github.io/
114 As of [#6869][6869], [`rust-analyzer`][ra_homepage] can understand that Clippy uses compiler-internals
115 using `extern crate` when `package.metadata.rust-analyzer.rustc_private` is set to `true` in Clippy's `Cargo.toml.`
116 You will require a `nightly` toolchain with the `rustc-dev` component installed.
117 Make sure that in the `rust-analyzer` configuration, you set
119 { "rust-analyzer.rustcSource": "discover" }
123 { "rust-analyzer.updates.channel": "nightly" }
125 You should be able to see information on things like `Expr` or `EarlyContext` now if you hover them, also
126 a lot more type hints.
127 This will work with `rust-analyzer 2021-03-15` shipped in nightly `1.52.0-nightly (107896c32 2021-03-15)` or later.
129 [ra_homepage]: https://rust-analyzer.github.io/
130 [6869]: https://github.com/rust-lang/rust-clippy/pull/6869
134 [`clippy_lints/src/lib.rs`][lint_crate_entry] imports all the different lint modules and registers in the [`LintStore`].
135 For example, the [`else_if_without_else`][else_if_without_else] lint is registered like this:
138 // ./clippy_lints/src/lib.rs
141 pub mod else_if_without_else;
144 pub fn register_plugins(store: &mut rustc_lint::LintStore, sess: &Session, conf: &Conf) {
146 store.register_early_pass(|| box else_if_without_else::ElseIfWithoutElse);
149 store.register_group(true, "clippy::restriction", Some("clippy_restriction"), vec![
151 LintId::of(&else_if_without_else::ELSE_IF_WITHOUT_ELSE),
157 The [`rustc_lint::LintStore`][`LintStore`] provides two methods to register lints:
158 [register_early_pass][reg_early_pass] and [register_late_pass][reg_late_pass]. Both take an object
159 that implements an [`EarlyLintPass`][early_lint_pass] or [`LateLintPass`][late_lint_pass] respectively. This is done in
160 every single lint. It's worth noting that the majority of `clippy_lints/src/lib.rs` is autogenerated by `cargo dev
161 update_lints`. When you are writing your own lint, you can use that script to save you some time.
164 // ./clippy_lints/src/else_if_without_else.rs
166 use rustc_lint::{EarlyLintPass, EarlyContext};
170 pub struct ElseIfWithoutElse;
174 impl EarlyLintPass for ElseIfWithoutElse {
175 // ... the functions needed, to make the lint work
179 The difference between `EarlyLintPass` and `LateLintPass` is that the methods of the `EarlyLintPass` trait only provide
180 AST information. The methods of the `LateLintPass` trait are executed after type checking and contain type information
181 via the `LateContext` parameter.
183 That's why the `else_if_without_else` example uses the `register_early_pass` function. Because the
184 [actual lint logic][else_if_without_else] does not depend on any type information.
186 [lint_crate_entry]: https://github.com/rust-lang/rust-clippy/blob/master/clippy_lints/src/lib.rs
187 [else_if_without_else]: https://github.com/rust-lang/rust-clippy/blob/4253aa7137cb7378acc96133c787e49a345c2b3c/clippy_lints/src/else_if_without_else.rs
188 [`LintStore`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_lint/struct.LintStore.html
189 [reg_early_pass]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_lint/struct.LintStore.html#method.register_early_pass
190 [reg_late_pass]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_lint/struct.LintStore.html#method.register_late_pass
191 [early_lint_pass]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_lint/trait.EarlyLintPass.html
192 [late_lint_pass]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_lint/trait.LateLintPass.html
194 ## Issue and PR triage
196 Clippy is following the [Rust triage procedure][triage] for issues and pull
199 However, we are a smaller project with all contributors being volunteers
200 currently. Between writing new lints, fixing issues, reviewing pull requests and
201 responding to issues there may not always be enough time to stay on top of it
204 Our highest priority is fixing [crashes][l-crash] and [bugs][l-bug], for example
205 an ICE in a popular crate that many other crates depend on. We don't
206 want Clippy to crash on your code and we want it to be as reliable as the
207 suggestions from Rust compiler errors.
209 We have prioritization labels and a sync-blocker label, which are described below.
210 - [P-low][p-low]: Requires attention (fix/response/evaluation) by a team member but isn't urgent.
211 - [P-medium][p-medium]: Should be addressed by a team member until the next sync.
212 - [P-high][p-high]: Should be immediately addressed and will require an out-of-cycle sync or a backport.
213 - [L-sync-blocker][l-sync-blocker]: An issue that "blocks" a sync.
214 Or rather: before the sync this should be addressed,
215 e.g. by removing a lint again, so it doesn't hit beta/stable.
219 We use a bot powered by [Homu][homu] to help automate testing and landing of pull
220 requests in Clippy. The bot's username is @bors.
222 You can find the Clippy bors queue [here][homu_queue].
224 If you have @bors permissions, you can find an overview of the available
225 commands [here][homu_instructions].
227 [triage]: https://forge.rust-lang.org/release/triage-procedure.html
228 [l-crash]: https://github.com/rust-lang/rust-clippy/labels/L-crash
229 [l-bug]: https://github.com/rust-lang/rust-clippy/labels/L-bug
230 [p-low]: https://github.com/rust-lang/rust-clippy/labels/P-low
231 [p-medium]: https://github.com/rust-lang/rust-clippy/labels/P-medium
232 [p-high]: https://github.com/rust-lang/rust-clippy/labels/P-high
233 [l-sync-blocker]: https://github.com/rust-lang/rust-clippy/labels/L-sync-blocker
234 [homu]: https://github.com/rust-lang/homu
235 [homu_instructions]: https://bors.rust-lang.org/
236 [homu_queue]: https://bors.rust-lang.org/queue/clippy
240 Contributions to Clippy should be made in the form of GitHub pull requests. Each pull request will
241 be reviewed by a core contributor (someone with permission to land patches) and either landed in the
242 main tree or given feedback for changes that would be required.
244 All code in this repository is under the [Apache-2.0] or the [MIT] license.
246 <!-- adapted from https://github.com/servo/servo/blob/master/CONTRIBUTING.md -->
248 [Apache-2.0]: https://www.apache.org/licenses/LICENSE-2.0
249 [MIT]: https://opensource.org/licenses/MIT