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 - [Getting started](#getting-started)
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 **Note: If this is your first time contributing to Clippy, you should
34 first read the [Basics docs](doc/basics.md).**
36 ### High level approach
38 1. Find something to fix/improve
39 2. Change code (likely some file in `clippy_lints/src/`)
40 3. Follow the instructions in the [Basics docs](doc/basics.md) to get set up
41 4. Run `cargo test` in the root directory and wiggle code until it passes
42 5. Open a PR (also can be done after 2. if you run into problems)
44 ### Finding something to fix/improve
46 All issues on Clippy are mentored, if you want help simply ask @Manishearth, @flip1995, @phansch
47 or @llogiq directly by mentioning them in the issue or over on [Zulip]. This list may be out of date.
48 All currently active mentors can be found [here](https://github.com/rust-lang/highfive/blob/master/highfive/configs/rust-lang/rust-clippy.json#L3)
50 Some issues are easier than others. The [`good-first-issue`] label can be used to find the easy
51 issues. You can use `@rustbot claim` to assign the issue to yourself.
53 There are also some abandoned PRs, marked with [`S-inactive-closed`].
54 Pretty often these PRs are nearly completed and just need some extra steps
55 (formatting, addressing review comments, ...) to be merged. If you want to
56 complete such a PR, please leave a comment in the PR and open a new one based
59 Issues marked [`T-AST`] involve simple matching of the syntax tree structure,
60 and are generally easier than [`T-middle`] issues, which involve types
63 [`T-AST`] issues will generally need you to match against a predefined syntax structure.
64 To figure out how this syntax structure is encoded in the AST, it is recommended to run
65 `rustc -Z unpretty=ast-tree` on an example of the structure and compare with the [nodes in the AST docs].
66 Usually the lint will end up to be a nested series of matches and ifs, [like so][deep-nesting].
67 But we can make it nest-less by using [let chains], [like this][nest-less].
69 [`E-medium`] issues are generally pretty easy too, though it's recommended you work on an [`good-first-issue`]
70 first. Sometimes they are only somewhat involved code wise, but not difficult per-se.
71 Note that [`E-medium`] issues may require some knowledge of Clippy internals or some
72 debugging to find the actual problem behind the issue.
74 [`T-middle`] issues can be more involved and require verifying types. The [`ty`] module contains a
75 lot of methods that are useful, though one of the most useful would be `expr_ty` (gives the type of
76 an AST expression). `match_def_path()` in Clippy's `utils` module can also be useful.
78 [`good-first-issue`]: https://github.com/rust-lang/rust-clippy/labels/good-first-issue
79 [`S-inactive-closed`]: https://github.com/rust-lang/rust-clippy/pulls?q=is%3Aclosed+label%3AS-inactive-closed
80 [`T-AST`]: https://github.com/rust-lang/rust-clippy/labels/T-AST
81 [`T-middle`]: https://github.com/rust-lang/rust-clippy/labels/T-middle
82 [`E-medium`]: https://github.com/rust-lang/rust-clippy/labels/E-medium
83 [`ty`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty
84 [nodes in the AST docs]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_ast/ast/
85 [deep-nesting]: https://github.com/rust-lang/rust-clippy/blob/5e4f0922911536f80d9591180fa604229ac13939/clippy_lints/src/mem_forget.rs#L31-L45
86 [let chains]: https://github.com/rust-lang/rust/pull/94927
87 [nest-less]: https://github.com/rust-lang/rust-clippy/blob/5e4f0922911536f80d9591180fa604229ac13939/clippy_lints/src/bit_mask.rs#L133-L159
91 Have a look at the [docs for writing lints][adding_lints] for more details.
93 If you want to add a new lint or change existing ones apart from bugfixing, it's
94 also a good idea to give the [stability guarantees][rfc_stability] and
95 [lint categories][rfc_lint_cats] sections of the [Clippy 1.0 RFC][clippy_rfc] a
98 [adding_lints]: https://github.com/rust-lang/rust-clippy/blob/master/doc/adding_lints.md
99 [clippy_rfc]: https://github.com/rust-lang/rfcs/blob/master/text/2476-clippy-uno.md
100 [rfc_stability]: https://github.com/rust-lang/rfcs/blob/master/text/2476-clippy-uno.md#stability-guarantees
101 [rfc_lint_cats]: https://github.com/rust-lang/rfcs/blob/master/text/2476-clippy-uno.md#lint-audit-and-categories
103 ## Getting code-completion for rustc internals to work
106 Unfortunately, [`IntelliJ Rust`][IntelliJ_rust_homepage] does not (yet?) understand how Clippy uses compiler-internals
107 using `extern crate` and it also needs to be able to read the source files of the rustc-compiler which are not
108 available via a `rustup` component at the time of writing.
109 To work around this, you need to have a copy of the [rustc-repo][rustc_repo] available which can be obtained via
110 `git clone https://github.com/rust-lang/rust/`.
111 Then you can run a `cargo dev` command to automatically make Clippy use the rustc-repo via path-dependencies
112 which `IntelliJ Rust` will be able to understand.
113 Run `cargo dev setup intellij --repo-path <repo-path>` where `<repo-path>` is a path to the rustc repo
115 The command will add path-dependencies pointing towards rustc-crates inside the rustc repo to
116 Clippy's `Cargo.toml`s and should allow `IntelliJ Rust` to understand most of the types that Clippy uses.
117 Just make sure to remove the dependencies again before finally making a pull request!
119 [rustc_repo]: https://github.com/rust-lang/rust/
120 [IntelliJ_rust_homepage]: https://intellij-rust.github.io/
123 As of [#6869][6869], [`rust-analyzer`][ra_homepage] can understand that Clippy uses compiler-internals
124 using `extern crate` when `package.metadata.rust-analyzer.rustc_private` is set to `true` in Clippy's `Cargo.toml.`
125 You will require a `nightly` toolchain with the `rustc-dev` component installed.
126 Make sure that in the `rust-analyzer` configuration, you set
128 { "rust-analyzer.rustcSource": "discover" }
132 { "rust-analyzer.updates.channel": "nightly" }
134 You should be able to see information on things like `Expr` or `EarlyContext` now if you hover them, also
135 a lot more type hints.
136 This will work with `rust-analyzer 2021-03-15` shipped in nightly `1.52.0-nightly (107896c32 2021-03-15)` or later.
138 [ra_homepage]: https://rust-analyzer.github.io/
139 [6869]: https://github.com/rust-lang/rust-clippy/pull/6869
143 [`clippy_lints/src/lib.rs`][lint_crate_entry] imports all the different lint modules and registers in the [`LintStore`].
144 For example, the [`else_if_without_else`][else_if_without_else] lint is registered like this:
147 // ./clippy_lints/src/lib.rs
150 pub mod else_if_without_else;
153 pub fn register_plugins(store: &mut rustc_lint::LintStore, sess: &Session, conf: &Conf) {
155 store.register_early_pass(|| box else_if_without_else::ElseIfWithoutElse);
158 store.register_group(true, "clippy::restriction", Some("clippy_restriction"), vec![
160 LintId::of(&else_if_without_else::ELSE_IF_WITHOUT_ELSE),
166 The [`rustc_lint::LintStore`][`LintStore`] provides two methods to register lints:
167 [register_early_pass][reg_early_pass] and [register_late_pass][reg_late_pass]. Both take an object
168 that implements an [`EarlyLintPass`][early_lint_pass] or [`LateLintPass`][late_lint_pass] respectively. This is done in
169 every single lint. It's worth noting that the majority of `clippy_lints/src/lib.rs` is autogenerated by `cargo dev
170 update_lints`. When you are writing your own lint, you can use that script to save you some time.
173 // ./clippy_lints/src/else_if_without_else.rs
175 use rustc_lint::{EarlyLintPass, EarlyContext};
179 pub struct ElseIfWithoutElse;
183 impl EarlyLintPass for ElseIfWithoutElse {
184 // ... the functions needed, to make the lint work
188 The difference between `EarlyLintPass` and `LateLintPass` is that the methods of the `EarlyLintPass` trait only provide
189 AST information. The methods of the `LateLintPass` trait are executed after type checking and contain type information
190 via the `LateContext` parameter.
192 That's why the `else_if_without_else` example uses the `register_early_pass` function. Because the
193 [actual lint logic][else_if_without_else] does not depend on any type information.
195 [lint_crate_entry]: https://github.com/rust-lang/rust-clippy/blob/master/clippy_lints/src/lib.rs
196 [else_if_without_else]: https://github.com/rust-lang/rust-clippy/blob/4253aa7137cb7378acc96133c787e49a345c2b3c/clippy_lints/src/else_if_without_else.rs
197 [`LintStore`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_lint/struct.LintStore.html
198 [reg_early_pass]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_lint/struct.LintStore.html#method.register_early_pass
199 [reg_late_pass]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_lint/struct.LintStore.html#method.register_late_pass
200 [early_lint_pass]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_lint/trait.EarlyLintPass.html
201 [late_lint_pass]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_lint/trait.LateLintPass.html
203 ## Issue and PR triage
205 Clippy is following the [Rust triage procedure][triage] for issues and pull
208 However, we are a smaller project with all contributors being volunteers
209 currently. Between writing new lints, fixing issues, reviewing pull requests and
210 responding to issues there may not always be enough time to stay on top of it
213 Our highest priority is fixing [crashes][l-crash] and [bugs][l-bug], for example
214 an ICE in a popular crate that many other crates depend on. We don't
215 want Clippy to crash on your code and we want it to be as reliable as the
216 suggestions from Rust compiler errors.
218 We have prioritization labels and a sync-blocker label, which are described below.
219 - [P-low][p-low]: Requires attention (fix/response/evaluation) by a team member but isn't urgent.
220 - [P-medium][p-medium]: Should be addressed by a team member until the next sync.
221 - [P-high][p-high]: Should be immediately addressed and will require an out-of-cycle sync or a backport.
222 - [L-sync-blocker][l-sync-blocker]: An issue that "blocks" a sync.
223 Or rather: before the sync this should be addressed,
224 e.g. by removing a lint again, so it doesn't hit beta/stable.
228 We use a bot powered by [Homu][homu] to help automate testing and landing of pull
229 requests in Clippy. The bot's username is @bors.
231 You can find the Clippy bors queue [here][homu_queue].
233 If you have @bors permissions, you can find an overview of the available
234 commands [here][homu_instructions].
236 [triage]: https://forge.rust-lang.org/release/triage-procedure.html
237 [l-crash]: https://github.com/rust-lang/rust-clippy/labels/L-crash
238 [l-bug]: https://github.com/rust-lang/rust-clippy/labels/L-bug
239 [p-low]: https://github.com/rust-lang/rust-clippy/labels/P-low
240 [p-medium]: https://github.com/rust-lang/rust-clippy/labels/P-medium
241 [p-high]: https://github.com/rust-lang/rust-clippy/labels/P-high
242 [l-sync-blocker]: https://github.com/rust-lang/rust-clippy/labels/L-sync-blocker
243 [homu]: https://github.com/rust-lang/homu
244 [homu_instructions]: https://bors.rust-lang.org/
245 [homu_queue]: https://bors.rust-lang.org/queue/clippy
249 Contributions to Clippy should be made in the form of GitHub pull requests. Each pull request will
250 be reviewed by a core contributor (someone with permission to land patches) and either landed in the
251 main tree or given feedback for changes that would be required.
253 All code in this repository is under the [Apache-2.0] or the [MIT] license.
255 <!-- adapted from https://github.com/servo/servo/blob/master/CONTRIBUTING.md -->
257 [Apache-2.0]: https://www.apache.org/licenses/LICENSE-2.0
258 [MIT]: https://opensource.org/licenses/MIT