rust-lang · bors · Jun 6, 2022 · Jun 16, 2021 · Aug 3, 2021 · Jan 21, 2022
diff --git a/.gitignore b/.gitignore
@@ -39,3 +39,6 @@ helper.txt
 *.iml
 .vscode
 .idea
+
+# mdbook generated output
+/book/book
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -13,44 +13,44 @@ anything, feel free to ask questions on issues or visit the `#clippy` on [Zulip]
 All contributors are expected to follow the [Rust Code of Conduct].
 
 - [Contributing to Clippy](#contributing-to-clippy)
-  - [Getting started](#getting-started)
-    - [High level approach](#high-level-approach)
-    - [Finding something to fix/improve](#finding-something-to-fiximprove)
+  - [The Clippy book](#the-clippy-book)
+  - [High level approach](#high-level-approach)
+  - [Finding something to fix/improve](#finding-something-to-fiximprove)
   - [Writing code](#writing-code)
   - [Getting code-completion for rustc internals to work](#getting-code-completion-for-rustc-internals-to-work)
     - [IntelliJ Rust](#intellij-rust)
     - [Rust Analyzer](#rust-analyzer)
   - [How Clippy works](#how-clippy-works)
-  - [Syncing changes between Clippy and `rust-lang/rust`](#syncing-changes-between-clippy-and-rust-langrust)
-    - [Patching git-subtree to work with big repos](#patching-git-subtree-to-work-with-big-repos)
-    - [Performing the sync from `rust-lang/rust` to Clippy](#performing-the-sync-from-rust-langrust-to-clippy)
-    - [Performing the sync from Clippy to `rust-lang/rust`](#performing-the-sync-from-clippy-to-rust-langrust)
-    - [Defining remotes](#defining-remotes)
   - [Issue and PR triage](#issue-and-pr-triage)
   - [Bors and Homu](#bors-and-homu)
   - [Contributions](#contributions)
 
 [Zulip]: https://rust-lang.zulipchat.com/#narrow/stream/clippy
 [Rust Code of Conduct]: https://www.rust-lang.org/policies/code-of-conduct
 
-## Getting started
+## The Clippy book
 
-**Note: If this is your first time contributing to Clippy, you should
-first read the [Basics docs](doc/basics.md).**
+If you're new to Clippy and don't know where to start the [Clippy book] includes
+a developer guide and is a good place to start your journey.
 
-### High level approach
+<!-- FIXME: Link to the deployed book, once it is deployed through CI -->
+[Clippy book]: book/src
+
+## 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 [Basics docs](doc/basics.md) to get set up
+3. Follow the instructions in the [Basics docs](book/src/development/basics.md)
+   to get set up
 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)
 
-### Finding something to fix/improve
+## Finding something to fix/improve
 
-All issues on Clippy are mentored, if you want help simply ask @Manishearth, @flip1995, @phansch
-or @llogiq directly by mentioning them in the issue or over on [Zulip]. This list may be out of date.
-All currently active mentors can be found [here](https://github.com/rust-lang/highfive/blob/master/highfive/configs/rust-lang/rust-clippy.json#L3)
+All issues on Clippy are mentored, if you want help simply ask someone from the
+Clippy team directly by mentioning them in the issue or over on [Zulip]. All
+currently active team members can be found
+[here](https://github.com/rust-lang/highfive/blob/master/highfive/configs/rust-lang/rust-clippy.json#L3)
 
 Some issues are easier than others. The [`good-first-issue`] label can be used to find the easy
 issues. You can use `@rustbot claim` to assign the issue to yourself.
@@ -91,20 +91,6 @@ an AST expression). `match_def_path()` in Clippy's `utils` module can also be us
 [let chains]: https://github.com/rust-lang/rust/pull/94927
 [nest-less]: https://github.com/rust-lang/rust-clippy/blob/5e4f0922911536f80d9591180fa604229ac13939/clippy_lints/src/bit_mask.rs#L133-L159
 
-## Writing code
-
-Have a look at the [docs for writing lints][adding_lints] for more details.
-
-If you want to add a new lint or change existing ones apart from bugfixing, it's
-also a good idea to give the [stability guarantees][rfc_stability] and
-[lint categories][rfc_lint_cats] sections of the [Clippy 1.0 RFC][clippy_rfc] a
-quick read.
-
-[adding_lints]: https://github.com/rust-lang/rust-clippy/blob/master/doc/adding_lints.md
-[clippy_rfc]: https://github.com/rust-lang/rfcs/blob/master/text/2476-clippy-uno.md
-[rfc_stability]: https://github.com/rust-lang/rfcs/blob/master/text/2476-clippy-uno.md#stability-guarantees
-[rfc_lint_cats]: https://github.com/rust-lang/rfcs/blob/master/text/2476-clippy-uno.md#lint-audit-and-categories
-
 ## Getting code-completion for rustc internals to work
 
 ### IntelliJ Rust
@@ -205,126 +191,6 @@ That's why the `else_if_without_else` example uses the `register_early_pass` fun
 [early_lint_pass]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_lint/trait.EarlyLintPass.html
 [late_lint_pass]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_lint/trait.LateLintPass.html
 
-## Syncing changes between Clippy and [`rust-lang/rust`]
-
-Clippy currently gets built with a pinned nightly version.
-
-In the `rust-lang/rust` repository, where rustc resides, there's a copy of Clippy
-that compiler hackers modify from time to time to adapt to changes in the unstable
-API of the compiler.
-
-We need to sync these changes back to this repository periodically, and the changes
-made to this repository in the meantime also need to be synced to the `rust-lang/rust` repository.
-
-To avoid flooding the `rust-lang/rust` PR queue, this two-way sync process is done
-in a bi-weekly basis if there's no urgent changes. This is done starting on the day of
-the Rust stable release and then every other week. That way we guarantee that we keep
-this repo up to date with the latest compiler API, and every feature in Clippy is available
-for 2 weeks in nightly, before it can get to beta. For reference, the first sync
-following this cadence was performed the 2020-08-27.
-
-This process is described in detail in the following sections. For general information
-about `subtree`s in the Rust repository see [Rust's `CONTRIBUTING.md`][subtree].
-
-### Patching git-subtree to work with big repos
-
-Currently, there's a bug in `git-subtree` that prevents it from working properly
-with the [`rust-lang/rust`] repo. There's an open PR to fix that, but it's stale.
-Before continuing with the following steps, we need to manually apply that fix to
-our local copy of `git-subtree`.
-
-You can get the patched version of `git-subtree` from [here][gitgitgadget-pr].
-Put this file under `/usr/lib/git-core` (taking a backup of the previous file)
-and make sure it has the proper permissions:
-
-```bash
-sudo cp --backup /path/to/patched/git-subtree.sh /usr/lib/git-core/git-subtree
-sudo chmod --reference=/usr/lib/git-core/git-subtree~ /usr/lib/git-core/git-subtree
-sudo chown --reference=/usr/lib/git-core/git-subtree~ /usr/lib/git-core/git-subtree
-```
-
-_Note:_ The first time running `git subtree push` a cache has to be built. This
-involves going through the complete Clippy history once. For this you have to
-increase the stack limit though, which you can do with `ulimit -s 60000`.
-Make sure to run the `ulimit` command from the same session you call git subtree.
-
-_Note:_ If you are a Debian user, `dash` is the shell used by default for scripts instead of `sh`.
-This shell has a hardcoded recursion limit set to 1000. In order to make this process work,
-you need to force the script to run `bash` instead. You can do this by editing the first
-line of the `git-subtree` script and changing `sh` to `bash`.
-
-### Performing the sync from [`rust-lang/rust`] to Clippy
-
-Here is a TL;DR version of the sync process (all of the following commands have
-to be run inside the `rust` directory):
-
-1. Clone the [`rust-lang/rust`] repository or make sure it is up to date.
-2. Checkout the commit from the latest available nightly. You can get it using `rustup check`.
-3. Sync the changes to the rust-copy of Clippy to your Clippy fork:
-    ```bash
-    # Make sure to change `your-github-name` to your github name in the following command. Also be
-    # sure to either use a net-new branch, e.g. `sync-from-rust`, or delete the branch beforehand
-    # because changes cannot be fast forwarded
-    git subtree push -P src/tools/clippy git@github.com:your-github-name/rust-clippy sync-from-rust
-    ```
-
-    _Note:_ This will directly push to the remote repository. You can also push
-    to your local copy by replacing the remote address with `/path/to/rust-clippy`
-    directory.
-
-    _Note:_ Most of the time you have to create a merge commit in the
-    `rust-clippy` repo (this has to be done in the Clippy repo, not in the
-    rust-copy of Clippy):
-    ```bash
-    git fetch origin && git fetch upstream
-    git checkout sync-from-rust
-    git merge upstream/master
-    ```
-4. Open a PR to `rust-lang/rust-clippy` and wait for it to get merged (to
-   accelerate the process ping the `@rust-lang/clippy` team in your PR and/or
-   ~~annoy~~ ask them in the [Zulip] stream.)
-
-### Performing the sync from Clippy to [`rust-lang/rust`]
-
-All of the following commands have to be run inside the `rust` directory.
-
-1. Make sure Clippy itself is up-to-date by following the steps outlined in the previous
-section if necessary.
-
-2. Sync the `rust-lang/rust-clippy` master to the rust-copy of Clippy:
-    ```bash
-    git checkout -b sync-from-clippy
-    git subtree pull -P src/tools/clippy https://github.com/rust-lang/rust-clippy master
-    ```
-3. Open a PR to [`rust-lang/rust`]
-
-### Defining remotes
-
-You may want to define remotes, so you don't have to type out the remote
-addresses on every sync. You can do this with the following commands (these
-commands still have to be run inside the `rust` directory):
-
-```bash
-# Set clippy-upstream remote for pulls
-$ git remote add clippy-upstream https://github.com/rust-lang/rust-clippy
-# Make sure to not push to the upstream repo
-$ git remote set-url --push clippy-upstream DISABLED
-# Set clippy-origin remote to your fork for pushes
-$ git remote add clippy-origin git@github.com:your-github-name/rust-clippy
-# Set a local remote
-$ git remote add clippy-local /path/to/rust-clippy
-```
-
-You can then sync with the remote names from above, e.g.:
-
-```bash
-$ git subtree push -P src/tools/clippy clippy-local sync-from-rust
-```
-
-[gitgitgadget-pr]: https://github.com/gitgitgadget/git/pull/493
-[subtree]: https://rustc-dev-guide.rust-lang.org/contributing.html#external-dependencies-subtree
-[`rust-lang/rust`]: https://github.com/rust-lang/rust
-
 ## Issue and PR triage
 
 Clippy is following the [Rust triage procedure][triage] for issues and pull

diff --git a/book/README.md b/book/README.md
@@ -0,0 +1,4 @@
+# Clippy Book
+
+This is the source for the Clippy Book. See the
+[book](src/infrastructure/book.md) for more information.
diff --git a/book/book.toml b/book/book.toml
@@ -0,0 +1,28 @@
+[book]
+authors = ["The Rust Clippy Developers"]
+language = "en"
+multilingual = false
+src = "src"
+title = "Clippy Documentation"
+
+[rust]
+edition = "2018"
+
+[output.html]
+edit-url-template = "https://github.com/rust-lang/rust-clippy/edit/master/book/{path}"
+git-repository-url = "https://github.com/rust-lang/rust-clippy/tree/master/book"
+mathjax-support = true
+site-url = "/rust-clippy/"
+
+[output.html.playground]
+editable = true
+line-numbers = true
+
+[output.html.search]
+boost-hierarchy = 2
+boost-paragraph = 1
+boost-title = 2
+expand = true
+heading-split-level = 2
+limit-results = 20
+use-boolean-and = true
diff --git a/book/src/README.md b/book/src/README.md
@@ -0,0 +1,34 @@
+# Clippy
+
+[![Clippy Test](https://github.com/rust-lang/rust-clippy/workflows/Clippy%20Test/badge.svg?branch=auto&event=push)](https://github.com/rust-lang/rust-clippy/actions?query=workflow%3A%22Clippy+Test%22+event%3Apush+branch%3Aauto)
+[![License: MIT OR Apache-2.0](https://img.shields.io/crates/l/clippy.svg)](#license)
+
+A collection of lints to catch common mistakes and improve your
+[Rust](https://github.com/rust-lang/rust) code.
+
+[There are over 500 lints included in this crate!](https://rust-lang.github.io/rust-clippy/master/index.html)
+
+Lints are divided into categories, each with a default [lint
+level](https://doc.rust-lang.org/rustc/lints/levels.html). You can choose how
+much Clippy is supposed to ~~annoy~~ help you by changing the lint level by
+category.
+
+| Category              | Description                                                                         | Default level |
+| --------------------- | ----------------------------------------------------------------------------------- | ------------- |
+| `clippy::all`         | all lints that are on by default (correctness, suspicious, style, complexity, perf) | **warn/deny** |
+| `clippy::correctness` | code that is outright wrong or useless                                              | **deny**      |
+| `clippy::suspicious`  | code that is most likely wrong or useless                                           | **warn**      |
+| `clippy::complexity`  | code that does something simple but in a complex way                                | **warn**      |
+| `clippy::perf`        | code that can be written to run faster                                              | **warn**      |
+| `clippy::style`       | code that should be written in a more idiomatic way                                 | **warn**      |
+| `clippy::pedantic`    | lints which are rather strict or might have false positives                         | allow         |
+| `clippy::nursery`     | new lints that are still under development                                          | allow         |
+| `clippy::cargo`       | lints for the cargo manifest                                                        | allow         |                                   | allow         |
+
+More to come, please [file an
+issue](https://github.com/rust-lang/rust-clippy/issues) if you have ideas!
+
+The [lint list](https://rust-lang.github.io/rust-clippy/master/index.html) also
+contains "restriction lints", which are for things which are usually not
+considered "bad", but may be useful to turn on in specific cases. These should
+be used very selectively, if at all.
diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md
@@ -0,0 +1,23 @@
+# Summary
+
+[Introduction](README.md)
+
+- [Installation](installation.md)
+- [Usage](usage.md)
+- [Configuration](configuration.md)
+- [Clippy's Lints](lints.md)
+- [Continuous Integration](continuous_integration/README.md)
+    - [GitHub Actions](continuous_integration/github_actions.md)
+    - [Travis CI](continuous_integration/travis.md)
+- [Development](development/README.md)
+    - [Basics](development/basics.md)
+    - [Adding Lints](development/adding_lints.md)
+    - [Common Tools](development/common_tools_writing_lints.md)
+    - [Infrastructure](development/infrastructure/README.md)
+        - [Syncing changes between Clippy and rust-lang/rust](development/infrastructure/sync.md)
+        - [Backporting Changes](development/infrastructure/backport.md)
+        - [Updating the Changelog](development/infrastructure/changelog_update.md)
+        - [Release a New Version](development/infrastructure/release.md)
+        - [The Clippy Book](development/infrastructure/book.md)
+    - [Proposals](development/proposals/README.md)
+        - [Roadmap 2021](development/proposals/roadmap-2021.md)
-Original file line number
+Diff line change
@@ Expand Up / @@ -39,3 +39,6 @@ helper.txt @@
     *.iml
     .vscode
     .idea
+    # mdbook generated output
+    /book/book