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` IRC channel on `irc.mozilla.org` or meet us in
12 `#clippy` on [Discord](https://discord.gg/rust-lang).
14 All contributors are expected to follow the [Rust Code of Conduct](http://www.rust-lang.org/conduct.html).
16 * [Getting started](#getting-started)
17 * [Finding something to fix/improve](#finding-something-to-fiximprove)
18 * [Writing code](#writing-code)
19 * [How Clippy works](#how-clippy-works)
20 * [Fixing nightly build failures](#fixing-build-failures-caused-by-rust)
21 * [Issue and PR Triage](#issue-and-pr-triage)
22 * [Bors and Homu](#bors-and-homu)
23 * [Contributions](#contributions)
29 1. Find something to fix/improve
30 2. Change code (likely some file in `clippy_lints/src/`)
31 3. Follow the instructions in the [docs for writing lints](doc/adding_lints.md) such as running the `setup-toolchain.sh` script
32 4. Run `cargo test` in the root directory and wiggle code until it passes
33 5. Open a PR (also can be done after 2. if you run into problems)
35 ### Finding something to fix/improve
37 All issues on Clippy are mentored, if you want help with a bug just ask @Manishearth, @llogiq, @mcarton or @oli-obk.
39 Some issues are easier than others. The [`good first issue`](https://github.com/rust-lang/rust-clippy/labels/good%20first%20issue)
40 label can be used to find the easy issues. If you want to work on an issue, please leave a comment
41 so that we can assign it to you!
43 There are also some abandoned PRs, marked with
44 [`S-inactive-closed`](https://github.com/rust-lang/rust-clippy/pulls?q=is%3Aclosed+label%3AS-inactive-closed).
45 Pretty often these PRs are nearly completed and just need some extra steps
46 (formatting, addressing review comments, ...) to be merged. If you want to
47 complete such a PR, please leave a comment in the PR and open a new one based
50 Issues marked [`T-AST`](https://github.com/rust-lang/rust-clippy/labels/T-AST) involve simple
51 matching of the syntax tree structure, and are generally easier than
52 [`T-middle`](https://github.com/rust-lang/rust-clippy/labels/T-middle) issues, which involve types
55 [`T-AST`](https://github.com/rust-lang/rust-clippy/labels/T-AST) issues will generally need you to match against a
56 predefined syntax structure. To figure out how this syntax structure is encoded in the AST, it is recommended to run
57 `rustc -Z ast-json` on an example of the structure and compare with the [nodes in the AST
58 docs](https://doc.rust-lang.org/nightly/nightly-rustc/syntax/ast). Usually the lint will end up to be a nested series of
59 matches and ifs, [like
60 so](https://github.com/rust-lang/rust-clippy/blob/de5ccdfab68a5e37689f3c950ed1532ba9d652a0/src/misc.rs#L34).
62 [`E-medium`](https://github.com/rust-lang/rust-clippy/labels/E-medium) issues are generally
63 pretty easy too, though it's recommended you work on an E-easy issue first. They are mostly classified
64 as `E-medium`, since they might be somewhat involved code wise, but not difficult per-se.
66 [`T-middle`](https://github.com/rust-lang/rust-clippy/labels/T-middle) issues can
67 be more involved and require verifying types. The
68 [`ty`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc/ty) module contains a
69 lot of methods that are useful, though one of the most useful would be `expr_ty` (gives the type of
70 an AST expression). `match_def_path()` in Clippy's `utils` module can also be useful.
74 Have a look at the [docs for writing lints](doc/adding_lints.md) for more details. [Llogiq's blog post on
75 lints](https://llogiq.github.io/2015/06/04/workflows.html) is also a nice primer to lint-writing, though it does get
76 into advanced stuff and may be a bit outdated.
78 If you want to add a new lint or change existing ones apart from bugfixing, it's
79 also a good idea to give the [stability guarantees][rfc_stability] and
80 [lint categories][rfc_lint_cats] sections of the [Clippy 1.0 RFC][clippy_rfc] a
85 Clippy is a [rustc compiler plugin][compiler_plugin]. The main entry point is at [`src/lib.rs`][main_entry]. In there,
86 the lint registration is delegated to the [`clippy_lints`][lint_crate] crate.
88 [`clippy_lints/src/lib.rs`][lint_crate_entry] imports all the different lint modules and registers them with the rustc
89 plugin registry. For example, the [`else_if_without_else`][else_if_without_else] lint is registered like this:
92 // ./clippy_lints/src/lib.rs
95 pub mod else_if_without_else;
98 pub fn register_plugins(reg: &mut rustc_driver::plugin::Registry) {
100 reg.register_early_lint_pass(box else_if_without_else::ElseIfWithoutElse);
103 reg.register_lint_group("clippy::restriction", vec![
105 else_if_without_else::ELSE_IF_WITHOUT_ELSE,
111 The [`plugin::PluginRegistry`][plugin_registry] provides two methods to register lints:
112 [register_early_lint_pass][reg_early_lint_pass] and [register_late_lint_pass][reg_late_lint_pass]. Both take an object
113 that implements an [`EarlyLintPass`][early_lint_pass] or [`LateLintPass`][late_lint_pass] respectively. This is done in
114 every single lint. It's worth noting that the majority of `clippy_lints/src/lib.rs` is autogenerated by `cargo dev
115 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
119 // ./clippy_lints/src/else_if_without_else.rs
121 use rustc_lint::{EarlyLintPass, EarlyContext};
125 pub struct ElseIfWithoutElse;
129 impl EarlyLintPass for ElseIfWithoutElse {
130 // ... the functions needed, to make the lint work
134 The difference between `EarlyLintPass` and `LateLintPass` is that the methods of the `EarlyLintPass` trait only provide
135 AST information. The methods of the `LateLintPass` trait are executed after type checking and contain type information
136 via the `LateContext` parameter.
138 That's why the `else_if_without_else` example uses the `register_early_lint_pass` function. Because the [actual lint
139 logic][else_if_without_else] does not depend on any type information.
141 ## Fixing build failures caused by Rust
143 Clippy will sometimes fail to build from source because building it depends on unstable internal Rust features. Most of
144 the times we have to adapt to the changes and only very rarely there's an actual bug in Rust. Fixing build failures
145 caused by Rust updates, can be a good way to learn about Rust internals.
147 In order to find out why Clippy does not work properly with a new Rust commit, you can use the [rust-toolstate commit
148 history][toolstate_commit_history]. You will then have to look for the last commit that contains `test-pass ->
149 build-fail` or `test-pass` -> `test-fail` for the `clippy-driver` component. [Here][toolstate_commit] is an example.
151 The commit message contains a link to the PR. The PRs are usually small enough to discover the breaking API change and
152 if they are bigger, they likely include some discussion that may help you to fix Clippy.
154 To check if Clippy is available for a specific target platform, you can check
155 the [rustup component history][rustup_component_history].
157 If you decide to make Clippy work again with a Rust commit that breaks it,
158 you probably want to install the latest Rust from master locally and run Clippy
159 using that version of Rust.
161 You can use [rustup-toolchain-install-master][rtim] to do that:
164 cargo install rustup-toolchain-install-master
165 rustup-toolchain-install-master --force -n master -c rustc-dev
166 rustup override set master
170 After fixing the build failure on this repository, we can submit a pull request
171 to [`rust-lang/rust`] to fix the toolstate.
173 To submit a pull request, you should follow these steps:
176 # Assuming you already cloned the rust-lang/rust repo and you're in the correct directory
177 git submodule update --remote src/tools/clippy
178 cargo update -p clippy
180 git commit -m "Update Clippy"
181 ./x.py test -i --stage 1 src/tools/clippy # This is optional and should succeed anyway
182 # Open a PR in rust-lang/rust
185 ## Issue and PR triage
187 Clippy is following the [Rust triage procedure][triage] for issues and pull
190 However, we are a smaller project with all contributors being volunteers
191 currently. Between writing new lints, fixing issues, reviewing pull requests and
192 responding to issues there may not always be enough time to stay on top of it
195 Our highest priority is fixing [crashes][l-crash] and [bugs][l-bug]. We don't
196 want Clippy to crash on your code and we want it to be as reliable as the
197 suggestions from Rust compiler errors.
201 We use a bot powered by [Homu][homu] to help automate testing and landing of pull
202 requests in Clippy. The bot's username is @bors.
204 You can find the Clippy bors queue [here][homu_queue].
206 If you have @bors permissions, you can find an overview of the available
207 commands [here][homu_instructions].
212 Contributions to Clippy should be made in the form of GitHub pull requests. Each pull request will
213 be reviewed by a core contributor (someone with permission to land patches) and either landed in the
214 main tree or given feedback for changes that would be required.
216 All code in this repository is under the [Apache-2.0](http://www.apache.org/licenses/LICENSE-2.0>)
217 or the [MIT](http://opensource.org/licenses/MIT) license.
219 <!-- adapted from https://github.com/servo/servo/blob/master/CONTRIBUTING.md -->
221 [main_entry]: https://github.com/rust-lang/rust-clippy/blob/c5b39a5917ffc0f1349b6e414fa3b874fdcf8429/src/lib.rs#L14
222 [lint_crate]: https://github.com/rust-lang/rust-clippy/tree/c5b39a5917ffc0f1349b6e414fa3b874fdcf8429/clippy_lints/src
223 [lint_crate_entry]: https://github.com/rust-lang/rust-clippy/blob/c5b39a5917ffc0f1349b6e414fa3b874fdcf8429/clippy_lints/src/lib.rs
224 [else_if_without_else]: https://github.com/rust-lang/rust-clippy/blob/c5b39a5917ffc0f1349b6e414fa3b874fdcf8429/clippy_lints/src/else_if_without_else.rs
225 [compiler_plugin]: https://doc.rust-lang.org/unstable-book/language-features/plugin.html#lint-plugins
226 [plugin_registry]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_plugin_impl/registry/struct.Registry.html
227 [reg_early_lint_pass]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_plugin_impl/registry/struct.Registry.html#method.register_early_lint_pass
228 [reg_late_lint_pass]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_plugin_impl/registry/struct.Registry.html#method.register_late_lint_pass
229 [early_lint_pass]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc/lint/trait.EarlyLintPass.html
230 [late_lint_pass]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc/lint/trait.LateLintPass.html
231 [toolstate_commit_history]: https://github.com/rust-lang-nursery/rust-toolstate/commits/master
232 [toolstate_commit]: https://github.com/rust-lang-nursery/rust-toolstate/commit/6ce0459f6bfa7c528ae1886492a3e0b5ef0ee547
233 [rtim]: https://github.com/kennytm/rustup-toolchain-install-master
234 [rustup_component_history]: https://mexus.github.io/rustup-components-history
235 [clippy_rfc]: https://github.com/rust-lang/rfcs/blob/master/text/2476-clippy-uno.md
236 [rfc_stability]: https://github.com/rust-lang/rfcs/blob/master/text/2476-clippy-uno.md#stability-guarantees
237 [rfc_lint_cats]: https://github.com/rust-lang/rfcs/blob/master/text/2476-clippy-uno.md#lint-audit-and-categories
238 [triage]: https://forge.rust-lang.org/triage-procedure.html
239 [l-crash]: https://github.com/rust-lang/rust-clippy/labels/L-crash%20%3Aboom%3A
240 [l-bug]: https://github.com/rust-lang/rust-clippy/labels/L-bug%20%3Abeetle%3A
241 [homu]: https://github.com/servo/homu
242 [homu_instructions]: https://buildbot2.rust-lang.org/homu/
243 [homu_queue]: https://buildbot2.rust-lang.org/homu/queue/clippy
244 [`rust-lang/rust`]: https://github.com/rust-lang/rust