doc/basics.md

   1 # Basics for hacking on Clippy
   2
   3 This document explains the basics for hacking on Clippy. Besides others, this
   4 includes how to build and test Clippy. For a more in depth description on
   5 the codebase take a look at [Adding Lints] or [Common Tools].
   6
   7 [Adding Lints]: https://github.com/rust-lang/rust-clippy/blob/master/doc/adding_lints.md
   8 [Common Tools]: https://github.com/rust-lang/rust-clippy/blob/master/doc/common_tools_writing_lints.md
   9
  10 - [Basics for hacking on Clippy](#basics-for-hacking-on-clippy)
  11   - [Get the code](#get-the-code)
  12   - [Building and Testing](#building-and-testing)
  13   - [`cargo dev`](#cargo-dev)
  14   - [PR](#pr)
  15
  16 ## Get the Code
  17
  18 First, make sure you have checked out the latest version of Clippy. If this is
  19 your first time working on Clippy, create a fork of the repository and clone it
  20 afterwards with the following command:
  21
  22 ```bash
  23 git clone git@github.com:<your-username>/rust-clippy
  24 ```
  25
  26 If you've already cloned Clippy in the past, update it to the latest version:
  27
  28 ```bash
  29 # upstream has to be the remote of the rust-lang/rust-clippy repo
  30 git fetch upstream
  31 # make sure that you are on the master branch
  32 git checkout master
  33 # rebase your master branch on the upstream master
  34 git rebase upstream/master
  35 # push to the master branch of your fork
  36 git push
  37 ```
  38
  39 ## Building and Testing
  40
  41 You can build and test Clippy like every other Rust project:
  42
  43 ```bash
  44 cargo build  # builds Clippy
  45 cargo test   # tests Clippy
  46 ```
  47
  48 Since Clippy's test suite is pretty big, there are some commands that only run a
  49 subset of Clippy's tests:
  50
  51 ```bash
  52 # only run UI tests
  53 cargo uitest
  54 # only run UI tests starting with `test_`
  55 TESTNAME="test_" cargo uitest
  56 # only run dogfood tests
  57 cargo test --test dogfood
  58 ```
  59
  60 If the output of a [UI test] differs from the expected output, you can update the
  61 reference file with:
  62
  63 ```bash
  64 cargo dev bless
  65 ```
  66
  67 For example, this is necessary, if you fix a typo in an error message of a lint
  68 or if you modify a test file to add a test case.
  69
  70 _Note:_ This command may update more files than you intended. In that case only
  71 commit the files you wanted to update.
  72
  73 [UI test]: https://rustc-dev-guide.rust-lang.org/tests/adding.html#guide-to-the-ui-tests
  74
  75 ## `cargo dev`
  76
  77 Clippy has some dev tools to make working on Clippy more convenient. These tools
  78 can be accessed through the `cargo dev` command. Available tools are listed
  79 below. To get more information about these commands, just call them with
  80 `--help`.
  81
  82 ```bash
  83 # formats the whole Clippy codebase and all tests
  84 cargo dev fmt
  85 # register or update lint names/groups/...
  86 cargo dev update_lints
  87 # create a new lint and register it
  88 cargo dev new_lint
  89 # (experimental) Setup Clippy to work with rust-analyzer
  90 cargo dev ra-setup
  91 ```
  92
  93 ## PR
  94
  95 We follow a rustc no merge-commit policy.
  96 See <https://rustc-dev-guide.rust-lang.org/contributing.html#opening-a-pr>.