Add documentation for basic Clippy hacking

CONTRIBUTING.md

@@ -32,7 +32,7 @@ High level approach:
 
 1. Find something to fix/improve
 2. Change code (likely some file in `clippy_lints/src/`)
-3. Follow the instructions in the [docs for writing lints](doc/adding_lints.md) such as running the `setup-toolchain.sh` script
+3. Follow the instructions in the [Basics docs](doc/basics.md) such as running the `setup-toolchain.sh` script
 4. Run `cargo test` in the root directory and wiggle code until it passes
 5. Open a PR (also can be done after 2. if you run into problems)
 

doc/adding_lints.md

@@ -27,10 +27,7 @@ because that's clearly a non-descriptive name.
 
 ## Setup
 
-When working on Clippy, you will need the current git master version of rustc,
-which can change rapidly. Make sure you're working near rust-clippy's master,
-and use the `setup-toolchain.sh` script to configure the appropriate toolchain
-for the Clippy directory.
+See the [Basics](basics.md#get-the-code) documentation.
 
 ## Getting Started
 

doc/basics.md

@@ -0,0 +1,106 @@
+# Basics for hacking on Clippy
+
+This document explains the basics for hacking on Clippy. Besides others, this
+includes how to set-up the development environment, how to build and how to test
+Clippy. For a more in depth description on the codebase take a look at [Adding
+Lints] or [Common Tools].
+
+[Adding Lints]: https://github.com/rust-lang/rust-clippy/blob/master/doc/adding_lints.md
+[Common Tools]: https://github.com/rust-lang/rust-clippy/blob/master/doc/common_tools_writing_lints.md
+
+- [Basics for hacking on Clippy](#basics-for-hacking-on-clippy)
+  - [Get the code](#get-the-code)
+  - [Setup](#setup)
+  - [Building and Testing](#building-and-testing)
+  - [`cargo dev`](#cargo-dev)
+
+## Get the Code
+
+First, make sure you have checked out the latest version of Clippy. If this is
+your first time working on Clippy, create a fork of the repository and clone it
+afterwards with the following command:
+
+```bash
+git clone git@github.com:<your-username>/rust-clippy
+```
+
+If you've already cloned Clippy in the past, update it to the latest version:
+
+```bash
+# upstream has to be the remote of the rust-lang/rust-clippy repo
+git fetch upstream
+# make sure that you are on the master branch
+git checkout master
+# rebase your master branch on the upstream master
+git rebase upstream/master
+# push to the master branch of your fork
+git push
+```
+
+## Setup
+
+Next we need to setup the toolchain to compile Clippy. Since Clippy heavily
+relies on compiler internals it is build with the latest rustc master. To get
+this toolchain, you can just use the `setup-toolchain.sh` script or use
+`rustup-toolchain-install-master`:
+
+```bash
+sh setup-toolchain.sh
+# OR
+cargo install rustup-toolchain-install-master
+rustup-toolchain-install-master -f -n master -c rustc-dev -c llvm-tools
+rustup override set master
+```
+
+## Building and Testing
+
+Once the `master` toolchain is installed, you can build and test Clippy like
+every other Rust project:
+
+```bash
+cargo build  # builds Clippy
+cargo test   # tests Clippy
+```
+
+Since Clippys test suite is pretty big, there are some commands that only run a
+subset of Clippys tests:
+
+```bash
+# only run UI tests
+cargo uitest
+# only run UI tests starting with `test_`
+TESTNAME="test_" cargo uitest
+# only run dogfood tests
+cargo test --test dogfood
+```
+
+If the output of a UI test differs from the expected output, you can update the
+reference file with:
+
+```bash
+sh tests/ui/update-all-references.sh
+```
+
+For example, this is necessary, if you fix a typo in an error message of a lint
+or if you modify a test file to add a test case.
+
+_Note:_ This command may update more files than you intended. In that case only
+commit the files you wanted to update.
+
+## `cargo dev`
+
+Clippy has some dev tools to make working on Clippy more convenient. These tools
+can be accessed through the `cargo dev` command. Available tools are listed
+below. To get more information about these commands, just call them with
+`--help`.
+
+```bash
+# formats the whole Clippy codebase and all tests
+cargo dev fmt
+# register or update lint names/groups/...
+cargo dev update_lints
+# create a new lint and register it
+cargo dev new_lint
+# (experimental) Setup Clippy to work with rust-analyzer
+cargo dev ra-setup
+```