X-Git-Url: https://git.lizzy.rs/?a=blobdiff_plain;f=CONTRIBUTING.md;h=16e1696706e250dd56ccd84392b78ef2dcabe772;hb=94e897851bd9e8d41f41ea8109592b38863217fc;hp=71a54d85249a569363b6eb95db7bfe416d8082f1;hpb=8ae82eb4ab8845e3c247c62d27549f16ecef5360;p=rust.git

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 71a54d85249..16e1696706e 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -4,47 +4,93 @@ Hello fellow Rustacean! Great to see your interest in compiler internals and lin
 
 ## Getting started
 
-All issues on Clippy are mentored, if you want help with a bug just ask @Manishearth or @llogiq.
+High level approach:
 
-Some issues are easier than others. The [E-easy](https://github.com/Manishearth/rust-clippy/labels/E-easy)
+1. Find something to fix/improve
+2. Change code (likely some file in `clippy_lints/src/`)
+3. Run `cargo test` in the root directory and wiggle code until it passes
+4. Open a PR (also can be done between 2. and 3. if you run into problems)
+
+### Finding something to fix/improve
+
+All issues on Clippy are mentored, if you want help with a bug just ask @Manishearth, @llogiq, @mcarton or @oli-obk.
+
+Some issues are easier than others. The [`good first issue`](https://github.com/rust-lang-nursery/rust-clippy/labels/good%20first%20issue)
 label can be used to find the easy issues. If you want to work on an issue, please leave a comment
 so that we can assign it to you!
 
-Issues marked [T-AST](https://github.com/Manishearth/rust-clippy/labels/T-AST) involve simple
+Issues marked [`T-AST`](https://github.com/rust-lang-nursery/rust-clippy/labels/T-AST) involve simple
 matching of the syntax tree structure, and are generally easier than
-[T-middle](https://github.com/Manishearth/rust-clippy/labels/T-middle) issues, which involve types
+[`T-middle`](https://github.com/rust-lang-nursery/rust-clippy/labels/T-middle) issues, which involve types
 and resolved paths.
 
-Issues marked [E-medium](https://github.com/Manishearth/rust-clippy/labels/E-medium) are generally
-pretty easy too, though it's recommended you work on an E-easy issue first.
+[`T-AST`](https://github.com/rust-lang-nursery/rust-clippy/labels/T-AST) issues will generally need you to match against a predefined syntax structure. To figure out
+how this syntax structure is encoded in the AST, it is recommended to run `rustc -Z ast-json` on an
+example of the structure and compare with the
+[nodes in the AST docs](https://doc.rust-lang.org/nightly/nightly-rustc/syntax/ast). Usually
+the lint will end up to be a nested series of matches and ifs,
+[like so](https://github.com/rust-lang-nursery/rust-clippy/blob/de5ccdfab68a5e37689f3c950ed1532ba9d652a0/src/misc.rs#L34).
+
+[`E-medium`](https://github.com/rust-lang-nursery/rust-clippy/labels/E-medium) issues are generally
+pretty easy too, though it's recommended you work on an E-easy issue first. They are mostly classified
+as `E-medium`, since they might be somewhat involved code wise, but not difficult per-se.
+
+[`T-middle`](https://github.com/rust-lang-nursery/rust-clippy/labels/T-middle) issues can
+be more involved and require verifying types. The
+[`ty`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc/ty) module contains a
+lot of methods that are useful, though one of the most useful would be `expr_ty` (gives the type of
+an AST expression). `match_def_path()` in Clippy's `utils` module can also be useful.
+
+### Writing code
+
+Compiling clippy from scratch can take almost a minute or more depending on your machine.
+However, since Rust 1.24.0 incremental compilation is enabled by default and compile times for small changes should be quick.
 
 [Llogiq's blog post on lints](https://llogiq.github.io/2015/06/04/workflows.html) is a nice primer
 to lint-writing, though it does get into advanced stuff. Most lints consist of an implementation of
 `LintPass` with one or more of its default methods overridden. See the existing lints for examples
 of this.
 
-T-AST issues will generally need you to match against a predefined syntax structure. To figure out
-how this syntax structure is encoded in the AST, it is recommended to run `rustc -Z ast-json` on an
-example of the structure and compare with the
-[nodes in the AST docs](http://manishearth.github.io/rust-internals-docs/syntax/ast/). Usually
-the lint will end up to be a nested series of matches and ifs,
-[like so](https://github.com/Manishearth/rust-clippy/blob/de5ccdfab68a5e37689f3c950ed1532ba9d652a0/src/misc.rs#L34).
 
-T-middle issues can be more involved and require verifying types. The
-[`ty`](http://manishearth.github.io/rust-internals-docs/rustc/ty) module contains a
-lot of methods that are useful, though one of the most useful would be `expr_ty` (gives the type of
-an AST expression). `match_def_path()` in Clippy's `utils` module can also be useful.
+#### Author lint
 
-Compiling clippy can take almost a minute or more depending on your machine.
-You can set the environment flag `CARGO_INCREMENTAL=1` to cut down that time to
-almost a third on average, depending on the influence your change has.
+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.
 
-Clippy uses UI tests. UI tests check that the output of the compiler is exactly as expected.
-Of course there's little sense in writing the output yourself or copying it around.
-Therefore you can simply run `tests/ui/update-all-references.sh` and check whether
-the output looks as you expect with `git diff`. Commit all `*.stderr` files, too.
+Create a new UI test with the pattern you want to match:
+
+```rust
+// ./tests/ui/my_lint.rs
+
+// The custom_attribute needs to be enabled for the author lint to work
+#![feature(plugin, custom_attribute)]
+
+fn main() {
+    #[clippy(author)]
+    let arr: [i32; 1] = [7]; // Replace line with the code you want to match
+}
+```
+
+Now you run `TESTNAME=ui/my_lint cargo test --test compile-test` to produce
+the file with the generated code:
+
+```rust
+// ./tests/ui/my_lint.stdout
+
+if_chain! {
+    if let Expr_::ExprArray(ref elements) = stmt.node;
+    if elements.len() == 1;
+    if let Expr_::ExprLit(ref lit) = elements[0].node;
+    if let LitKind::Int(7, _) = lit.node;
+    then {
+        // report your lint here
+    }
+}
+```
+
+#### Documentation
+
+Please document your lint with a doc comment akin to the following:
 
-Also please document your lint with a doc comment akin to the following:
 ```rust
 /// **What it does:** Checks for ... (describe what the lint matches).
 ///
@@ -53,12 +99,44 @@ Also please document your lint with a doc comment akin to the following:
 /// **Known problems:** None. (Or describe where it could go wrong.)
 ///
 /// **Example:**
+///
 /// ```rust
-/// Insert a short example if you have one.
+/// // Bad
+/// Insert a short example of code that triggers the lint
+///
+/// // Good
+/// Insert a short example of improved code that doesn't trigger the lint
 /// ```
 ```
 
-Our `util/update_wiki.py` script can then add your lint docs to the wiki.
+Once your lint is merged it will show up in the [lint list](https://rust-lang-nursery.github.io/rust-clippy/master/index.html)
+
+### Running test suite
+
+Clippy uses UI tests. UI tests check that the output of the compiler is exactly as expected.
+Of course there's little sense in writing the output yourself or copying it around.
+Therefore you can simply run `tests/ui/update-all-references.sh` (after running
+`cargo test`) and check whether the output looks as you expect with `git diff`. Commit all
+`*.stderr` files, too.
+
+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:
+
+```bash
+TESTNAME=ui/empty_line_after_outer_attr cargo test --test compile-test
+```
+
+### Testing manually
+
+Manually testing against an example file is useful if you have added some
+`println!`s and test suite output becomes unreadable.  To try clippy with your
+local modifications, run `cargo run --bin clippy-driver -- -L ./target/debug input.rs` from the
+working copy root. Your test file, here `input.rs`, needs to have clippy
+enabled as a plugin:
+
+```rust
+#![feature(plugin)]
+#![plugin(clippy)]
+```
 
 ## Contributions