Merge remote-tracking branch 'upstream/master' into 503-hover-doc-links

6 files changed, 392 insertions, 313 deletions

diff --git a/docs/dev/README.md b/docs/dev/README.md
index 417352c9d..36edddc70 100644
--- a/docs/dev/README.md
+++ b/docs/dev/README.md
@@ -14,7 +14,7 @@ To learn more about how rust-analyzer works, see
 
 We also publish rustdoc docs to pages:
 
-https://rust-analyzer.github.io/rust-analyzer/ra_ide/
+https://rust-analyzer.github.io/rust-analyzer/ide/
 
 Various organizational and process issues are discussed in this document.
 
@@ -50,271 +50,85 @@ We use bors-ng to enforce the [not rocket science](https://graydon2.dreamwidth.o
 
 You can run `cargo xtask install-pre-commit-hook` to install git-hook to run rustfmt on commit.
 
-# Code organization
-
-All Rust code lives in the `crates` top-level directory, and is organized as a
-single Cargo workspace. The `editors` top-level directory contains code for
-integrating with editors. Currently, it contains the plugin for VS Code (in
-TypeScript). The `docs` top-level directory contains both developer and user
-documentation.
-
-We have some automation infra in Rust in the `xtask` package. It contains
-stuff like formatting checking, code generation and powers `cargo xtask install`.
-The latter syntax is achieved with the help of cargo aliases (see `.cargo`
-directory).
-
 # Launching rust-analyzer
 
-Debugging the language server can be tricky: LSP is rather chatty, so driving it
-from the command line is not really feasible, driving it via VS Code requires
-interacting with two processes.
+Debugging the language server can be tricky.
+LSP is rather chatty, so driving it from the command line is not really feasible, driving it via VS Code requires interacting with two processes.
 
-For this reason, the best way to see how rust-analyzer works is to find a
-relevant test and execute it (VS Code includes an action for running a single
-test).
+For this reason, the best way to see how rust-analyzer works is to find a relevant test and execute it.
+VS Code & Emacs include an action for running a single test.
 
-However, launching a VS Code instance with a locally built language server is
-possible. There's **"Run Extension (Debug Build)"** launch configuration for this.
+Launching a VS Code instance with a locally built language server is also possible.
+There's **"Run Extension (Debug Build)"** launch configuration for this in VS Code.
 
-In general, I use one of the following workflows for fixing bugs and
-implementing features.
+In general, I use one of the following workflows for fixing bugs and implementing features:
 
-If the problem concerns only internal parts of rust-analyzer (i.e. I don't need
-to touch the `rust-analyzer` crate or TypeScript code), there is a unit-test for it.
-So, I use **Rust Analyzer: Run** action in VS Code to run this single test, and
-then just do printf-driven development/debugging. As a sanity check after I'm
-done, I use `cargo xtask install --server` and **Reload Window** action in VS
-Code to sanity check that the thing works as I expect.
+If the problem concerns only internal parts of rust-analyzer (i.e. I don't need to touch the `rust-analyzer` crate or TypeScript code), there is a unit-test for it.
+So, I use **Rust Analyzer: Run** action in VS Code to run this single test, and then just do printf-driven development/debugging.
+As a sanity check after I'm done, I use `cargo xtask install --server` and **Reload Window** action in VS Code to verify that the thing works as I expect.
 
-If the problem concerns only the VS Code extension, I use **Run Installed Extension**
-launch configuration from `launch.json`. Notably, this uses the usual
-`rust-analyzer` binary from `PATH`. For this, it is important to have the following
-in your `settings.json` file:
+If the problem concerns only the VS Code extension, I use **Run Installed Extension** launch configuration from `launch.json`.
+Notably, this uses the usual `rust-analyzer` binary from `PATH`.
+For this, it is important to have the following in your `settings.json` file:
 ```json
 {
     "rust-analyzer.serverPath": "rust-analyzer"
 }
 ```
-After I am done with the fix, I use `cargo
-xtask install --client-code` to try the new extension for real.
-
-If I need to fix something in the `rust-analyzer` crate, I feel sad because it's
-on the boundary between the two processes, and working there is slow. I usually
-just `cargo xtask install --server` and poke changes from my live environment.
-Note that this uses `--release`, which is usually faster overall, because
-loading stdlib into debug version of rust-analyzer takes a lot of time. To speed
-things up, sometimes I open a temporary hello-world project which has
-`"rust-analyzer.withSysroot": false` in `.code/settings.json`. This flag causes
-rust-analyzer to skip loading the sysroot, which greatly reduces the amount of
-things rust-analyzer needs to do, and makes printf's more useful. Note that you
-should only use the `eprint!` family of macros for debugging: stdout is used for LSP
-communication, and `print!` would break it.
-
-If I need to fix something simultaneously in the server and in the client, I
-feel even more sad. I don't have a specific workflow for this case.
-
-Additionally, I use `cargo run --release -p rust-analyzer -- analysis-stats
-path/to/some/rust/crate` to run a batch analysis. This is primarily useful for
-performance optimizations, or for bug minimization.
-
-# Code Style & Review Process
-
-Our approach to "clean code" is two-fold:
-
-* We generally don't block PRs on style changes.
-* At the same time, all code in rust-analyzer is constantly refactored.
-
-It is explicitly OK for a reviewer to flag only some nits in the PR, and then send a follow-up cleanup PR for things which are easier to explain by example, cc-ing the original author.
-Sending small cleanup PRs (like renaming a single local variable) is encouraged.
-
-## Scale of Changes
-
-Everyone knows that it's better to send small & focused pull requests.
-The problem is, sometimes you *have* to, eg, rewrite the whole compiler, and that just doesn't fit into a set of isolated PRs.
-
-The main things to keep an eye on are the boundaries between various components.
-There are three kinds of changes:
-
-1. Internals of a single component are changed.
-   Specifically, you don't change any `pub` items.
-   A good example here would be an addition of a new assist.
-
-2. API of a component is expanded.
-   Specifically, you add a new `pub` function which wasn't there before.
-   A good example here would be expansion of assist API, for example, to implement lazy assists or assists groups.
-
-3. A new dependency between components is introduced.
-   Specifically, you add a `pub use` reexport from another crate or you add a new line to the `[dependencies]` section of `Cargo.toml`.
-   A good example here would be adding reference search capability to the assists crates.
-
-For the first group, the change is generally merged as long as:
-
-* it works for the happy case,
-* it has tests,
-* it doesn't panic for the unhappy case.
-
-For the second group, the change would be subjected to quite a bit of scrutiny and iteration.
-The new API needs to be right (or at least easy to change later).
-The actual implementation doesn't matter that much.
-It's very important to minimize the amount of changed lines of code for changes of the second kind.
-Often, you start doing a change of the first kind, only to realise that you need to elevate to a change of the second kind.
-In this case, we'll probably ask you to split API changes into a separate PR.
-
-Changes of the third group should be pretty rare, so we don't specify any specific process for them.
-That said, adding an innocent-looking `pub use` is a very simple way to break encapsulation, keep an eye on it!
-
-Note: if you enjoyed this abstract hand-waving about boundaries, you might appreciate
-https://www.tedinski.com/2018/02/06/system-boundaries.html
-
-## Minimal Tests
-
-Most tests in rust-analyzer start with a snippet of Rust code.
-This snippets should be minimal -- if you copy-paste a snippet of real code into the tests, make sure to remove everything which could be removed.
-There are many benefits to this:
-
-* less to read or to scroll past
-* easier to understand what exactly is tested
-* less stuff printed during printf-debugging
-* less time to run test
-
-It also makes sense to format snippets more compactly (for example, by placing enum defitions like `enum E { Foo, Bar }` on a single line),
-as long as they are still readable.
-
-## Order of Imports
-
-We separate import groups with blank lines
-
-```rust
-mod x;
-mod y;
-
-use std::{ ... }
-
-use crate_foo::{ ... }
-use crate_bar::{ ... }
-
-use crate::{}
-
-use super::{} // but prefer `use crate::`
-```
-
-## Import Style
-
-Items from `hir` and `ast` should be used qualified:
-
-```rust
-// Good
-use ra_syntax::ast;
-
-fn frobnicate(func: hir::Function, strukt: ast::StructDef) {}
-
-// Not as good
-use hir::Function;
-use ra_syntax::ast::StructDef;
-
-fn frobnicate(func: Function, strukt: StructDef) {}
-```
-
-Avoid local `use MyEnum::*` imports.
-
-Prefer `use crate::foo::bar` to `use super::bar`.
-
-## Order of Items
-
-Optimize for the reader who sees the file for the first time, and wants to get the general idea about what's going on.
-People read things from top to bottom, so place most important things first.
-
-Specifically, if all items except one are private, always put the non-private item on top.
-
-Put `struct`s and `enum`s first, functions and impls last.
-
-Do
-
-```rust
-// Good
-struct Foo {
-    bars: Vec<Bar>
-}
-
-struct Bar;
-```
-
-rather than
+After I am done with the fix, I use `cargo xtask install --client-code` to try the new extension for real.
 
-```rust
-// Not as good
-struct Bar;
-
-struct Foo {
-    bars: Vec<Bar>
-}
-```
+If I need to fix something in the `rust-analyzer` crate, I feel sad because it's on the boundary between the two processes, and working there is slow.
+I usually just `cargo xtask install --server` and poke changes from my live environment.
+Note that this uses `--release`, which is usually faster overall, because loading stdlib into debug version of rust-analyzer takes a lot of time.
+To speed things up, sometimes I open a temporary hello-world project which has `"rust-analyzer.withSysroot": false` in `.code/settings.json`.
+This flag causes rust-analyzer to skip loading the sysroot, which greatly reduces the amount of things rust-analyzer needs to do, and makes printf's more useful.
+Note that you should only use the `eprint!` family of macros for debugging: stdout is used for LSP communication, and `print!` would break it.
 
-## Variable Naming
+If I need to fix something simultaneously in the server and in the client, I feel even more sad.
+I don't have a specific workflow for this case.
 
-We generally use boring and long names for local variables ([yay code completion](https://github.com/rust-analyzer/rust-analyzer/pull/4162#discussion_r417130973)).
-The default name is a lowercased name of the type: `global_state: GlobalState`.
-Avoid ad-hoc acronyms and contractions, but use the ones that exist consistently (`db`, `ctx`, `acc`).
-The default name for "result of the function" local variable is `res`.
+Additionally, I use `cargo run --release -p rust-analyzer -- analysis-stats path/to/some/rust/crate` to run a batch analysis.
+This is primarily useful for performance optimizations, or for bug minimization.
 
-## Collection types
+## Parser Tests
 
-We prefer `rustc_hash::FxHashMap` and `rustc_hash::FxHashSet` instead of the ones in `std::collections`.
-They use a hasher that's slightly faster and using them consistently will reduce code size by some small amount.
+Tests for the parser (`parser`) live in the `syntax` crate (see `test_data` directory).
+There are two kinds of tests:
 
-## Preconditions
+* Manually written test cases in `parser/ok` and `parser/err`
+* "Inline" tests in `parser/inline` (these are generated) from comments in `parser` crate.
 
-Function preconditions should generally be expressed in types and provided by the caller (rather than checked by callee):
+The purpose of inline tests is not to achieve full coverage by test cases, but to explain to the reader of the code what each particular `if` and `match` is responsible for.
+If you are tempted to add a large inline test, it might be a good idea to leave only the simplest example in place, and move the test to a manual `parser/ok` test.
 
-```rust
-// Good
-fn frbonicate(walrus: Walrus) {
-    ...
-}
+To update test data, run with `UPDATE_EXPECT` variable:
 
-// Not as good
-fn frobnicate(walrus: Option<Walrus>) {
-    let walrus = match walrus {
-        Some(it) => it,
-        None => return,
-    };
-    ...
-}
+```bash
+env UPDATE_EXPECT=1 cargo qt
 ```
 
-## Premature Pessimization
-
-While we don't specifically optimize code yet, avoid writing code which is slower than it needs to be.
-Don't allocate a `Vec` where an iterator would do, don't allocate strings needlessly.
+After adding a new inline test you need to run `cargo xtest codegen` and also update the test data as described above.
 
-```rust
-// Good
-use itertools::Itertools;
+## TypeScript Tests
 
-let (first_word, second_word) = match text.split_ascii_whitespace().collect_tuple() {
-    Some(it) => it,
-    None => return,
-}
+If you change files under `editors/code` and would like to run the tests and linter, install npm and run:
 
-// Not as good
-let words = text.split_ascii_whitespace().collect::<Vec<_>>();
-if words.len() != 2 {
-    return
-}
+```bash
+cd editors/code
+npm ci
+npm run lint
 ```
 
-## Documentation
-
-For `.md` and `.adoc` files, prefer a sentence-per-line format, don't wrap lines.
-If the line is too long, you want to split the sentence in two :-)
-
-## Commit Style
+# Code organization
 
-We don't have specific rules around git history hygiene.
-Maintaining clean git history is encouraged, but not enforced.
-We use rebase workflow, it's OK to rewrite history during PR review process.
+All Rust code lives in the `crates` top-level directory, and is organized as a single Cargo workspace.
+The `editors` top-level directory contains code for integrating with editors.
+Currently, it contains the plugin for VS Code (in TypeScript).
+The `docs` top-level directory contains both developer and user documentation.
 
-Avoid @mentioning people in commit messages and pull request descriptions (they are added to commit message by bors), as such messages create a lot of duplicate notification traffic during rebases.
+We have some automation infra in Rust in the `xtask` package.
+It contains stuff like formatting checking, code generation and powers `cargo xtask install`.
+The latter syntax is achieved with the help of cargo aliases (see `.cargo` directory).
 
 # Architecture Invariants
 
@@ -334,50 +148,31 @@ Internal representations are lowered to LSP in the `rust-analyzer` crate (the on
 
 ## IDE/Compiler split
 
-There's a semi-hard split between "compiler" and "IDE", at the `ra_hir` crate.
+There's a semi-hard split between "compiler" and "IDE", at the `hir` crate.
 Compiler derives new facts about source code.
 It explicitly acknowledges that not all info is available (i.e. you can't look at types during name resolution).
 
 IDE assumes that all information is available at all times.
 
-IDE should use only types from `ra_hir`, and should not depend on the underling compiler types.
-`ra_hir` is a facade.
+IDE should use only types from `hir`, and should not depend on the underling compiler types.
+`hir` is a facade.
 
 ## IDE API
 
-The main IDE crate (`ra_ide`) uses "Plain Old Data" for the API.
+The main IDE crate (`ide`) uses "Plain Old Data" for the API.
 Rather than talking in definitions and references, it talks in Strings and textual offsets.
 In general, API is centered around UI concerns -- the result of the call is what the user sees in the editor, and not what the compiler sees underneath.
 The results are 100% Rust specific though.
+Shout outs to LSP developers for popularizing the idea that "UI" is a good place to draw a boundary at.
 
-## Parser Tests
-
-Tests for the parser (`ra_parser`) live in the `ra_syntax` crate (see `test_data` directory).
-There are two kinds of tests:
-
-* Manually written test cases in `parser/ok` and `parser/err`
-* "Inline" tests in `parser/inline` (these are generated) from comments in `ra_parser` crate.
-
-The purpose of inline tests is not to achieve full coverage by test cases, but to explain to the reader of the code what each particular `if` and `match` is responsible for.
-If you are tempted to add a large inline test, it might be a good idea to leave only the simplest example in place, and move the test to a manual `parser/ok` test.
-
-To update test data, run with `UPDATE_EXPECT` variable:
-
-```bash
-env UPDATE_EXPECT=1 cargo qt
-```
+## CI
 
-After adding a new inline test you need to run `cargo xtest codegen` and also update the test data as described above.
+CI does not test rust-analyzer, CI is a core part of rust-analyzer, and is maintained with above average standard of quality.
+CI is reproducible -- it can only be broken by changes to files in this repository, any dependence on externalities is a bug.
 
-## TypeScript Tests
-
-If you change files under `editors/code` and would like to run the tests and linter, install npm and run:
+# Code Style & Review Process
 
-```bash
-cd editors/code
-npm ci
-npm run lint
-```
+Do see [./style.md](./style.md).
 
 # Logging
 
@@ -445,3 +240,34 @@ For measuring time of incremental analysis, use either of these:
 $ cargo run --release -p rust-analyzer -- analysis-bench ../chalk/ --highlight ../chalk/chalk-engine/src/logic.rs
 $ cargo run --release -p rust-analyzer -- analysis-bench ../chalk/ --complete ../chalk/chalk-engine/src/logic.rs:94:0
 ```
+
+# Release Process
+
+Release process is handled by `release`, `dist` and `promote` xtasks, `release` being the main one.
+
+`release` assumes that you have checkouts of `rust-analyzer`, `rust-analyzer.github.io`, and `rust-lang/rust` in the same directory:
+
+```
+./rust-analyzer
+./rust-analyzer.github.io
+./rust-rust-analyzer  # Note the name!
+```
+
+Additionally, it assumes that remote for `rust-analyzer` is called `upstream` (I use `origin` to point to my fork).
+
+Release steps:
+
+1. Inside rust-analyzer, run `cargo xtask release`. This will:
+   * checkout the `release` branch
+   * reset it to `upstream/nightly`
+   * push it to `upstream`. This triggers GitHub Actions which:
+     * runs `cargo xtask dist` to package binaries and VS Code extension
+     * makes a GitHub release
+     * pushes VS Code extension to the marketplace
+   * create new changelog in `rust-analyzer.github.io`
+   * create `rust-analyzer.github.io/git.log` file with the log of merge commits since last release
+2. While the release is in progress, fill-in the changelog using `git.log`
+3. Commit & push the changelog
+4. Tweet
+5. Inside `rust-analyzer`, run `cargo xtask promote` -- this will create a PR to rust-lang/rust updating rust-analyzer's submodule.
+   Self-approve the PR.
diff --git a/docs/dev/architecture.md b/docs/dev/architecture.md
index d0c6eea61..6f1377f2f 100644
--- a/docs/dev/architecture.md
+++ b/docs/dev/architecture.md
@@ -56,7 +56,7 @@ In particular, `cargo xtask codegen` generates:
 2. [`ast/generated`](https://github.com/rust-analyzer/rust-analyzer/blob/a0be39296d2925972cacd9fbf8b5fb258fad6947/crates/ra_syntax/src/ast/generated.rs)
   -- AST data structure.
 
-3. [`doc_tests/generated`](https://github.com/rust-analyzer/rust-analyzer/blob/a0be39296d2925972cacd9fbf8b5fb258fad6947/crates/ra_assists/src/doc_tests/generated.rs),
+3. [`doc_tests/generated`](https://github.com/rust-analyzer/rust-analyzer/blob/a0be39296d2925972cacd9fbf8b5fb258fad6947/crates/assists/src/doc_tests/generated.rs),
   [`test_data/parser/inline`](https://github.com/rust-analyzer/rust-analyzer/tree/a0be39296d2925972cacd9fbf8b5fb258fad6947/crates/ra_syntax/test_data/parser/inline)
   -- tests for assists and the parser.
 
@@ -64,7 +64,7 @@ The source for 1 and 2 is in [`ast_src.rs`](https://github.com/rust-analyzer/rus
 
 ## Code Walk-Through
 
-### `crates/ra_syntax`, `crates/ra_parser`
+### `crates/ra_syntax`, `crates/parser`
 
 Rust syntax tree structure and parser. See
 [RFC](https://github.com/rust-lang/rfcs/pull/2256) and [./syntax.md](./syntax.md) for some design notes.
@@ -92,17 +92,17 @@ in particular: it shows off various methods of working with syntax tree.
 See [#93](https://github.com/rust-analyzer/rust-analyzer/pull/93) for an example PR which
 fixes a bug in the grammar.
 
-### `crates/ra_db`
+### `crates/base_db`
 
 We use the [salsa](https://github.com/salsa-rs/salsa) crate for incremental and
 on-demand computation. Roughly, you can think of salsa as a key-value store, but
-it also can compute derived values using specified functions. The `ra_db` crate
+it also can compute derived values using specified functions. The `base_db` crate
 provides basic infrastructure for interacting with salsa. Crucially, it
 defines most of the "input" queries: facts supplied by the client of the
-analyzer. Reading the docs of the `ra_db::input` module should be useful:
+analyzer. Reading the docs of the `base_db::input` module should be useful:
 everything else is strictly derived from those inputs.
 
-### `crates/ra_hir*` crates
+### `crates/hir*` crates
 
 HIR provides high-level "object oriented" access to Rust code.
 
@@ -113,12 +113,12 @@ is responsible for guessing a HIR for a particular source position.
 
 Underneath, HIR works on top of salsa, using a `HirDatabase` trait.
 
-`ra_hir_xxx` crates have a strong ECS flavor, in that they work with raw ids and
+`hir_xxx` crates have a strong ECS flavor, in that they work with raw ids and
 directly query the database.
 
-The top-level `ra_hir` façade crate wraps ids into a more OO-flavored API.
+The top-level `hir` façade crate wraps ids into a more OO-flavored API.
 
-### `crates/ra_ide`
+### `crates/ide`
 
 A stateful library for analyzing many Rust files as they change. `AnalysisHost`
 is a mutable entity (clojure's atom) which holds the current state, incorporates
@@ -136,11 +136,11 @@ offsets and strings as output. This works on top of rich code model powered by
 
 ### `crates/rust-analyzer`
 
-An LSP implementation which wraps `ra_ide` into a language server protocol.
+An LSP implementation which wraps `ide` into a language server protocol.
 
 ### `ra_vfs`
 
-Although `hir` and `ra_ide` don't do any IO, we need to be able to read
+Although `hir` and `ide` don't do any IO, we need to be able to read
 files from disk at the end of the day. This is what `ra_vfs` does. It also
 manages overlays: "dirty" files in the editor, whose "true" contents is
 different from data on disk. This is more or less the single really
@@ -161,7 +161,7 @@ disk. For this reason, we try to avoid writing too many tests on this boundary:
 in a statically typed language, it's hard to make an error in the protocol
 itself if messages are themselves typed.
 
-The middle, and most important, boundary is `ra_ide`. Unlike
+The middle, and most important, boundary is `ide`. Unlike
 `rust-analyzer`, which exposes API, `ide` uses Rust API and is intended to
 use by various tools. Typical test creates an `AnalysisHost`, calls some
 `Analysis` functions and compares the results against expectation.
diff --git a/docs/dev/guide.md b/docs/dev/guide.md
index c3252f1f6..b5a5d7c93 100644
--- a/docs/dev/guide.md
+++ b/docs/dev/guide.md
@@ -40,8 +40,8 @@ terms of files and offsets, and **not** in terms of Rust concepts like structs,
 traits, etc. The "typed" API with Rust specific types is slightly lower in the
 stack, we'll talk about it later.
 
-[`AnalysisHost`]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/ra_ide_api/src/lib.rs#L265-L284
-[`Analysis`]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/ra_ide_api/src/lib.rs#L291-L478
+[`AnalysisHost`]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/ide_api/src/lib.rs#L265-L284
+[`Analysis`]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/ide_api/src/lib.rs#L291-L478
 
 The reason for this separation of `Analysis` and `AnalysisHost` is that we want to apply
 changes "uniquely", but we might also want to fork an `Analysis` and send it to
@@ -69,7 +69,7 @@ the `AnalysisHost::apply_change` method, which accepts a single argument, a
 "transaction", so it suffices to study its methods to understand all of the
 input data.
 
-[`AnalysisChange`]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/ra_ide_api/src/lib.rs#L119-L167
+[`AnalysisChange`]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/ide_api/src/lib.rs#L119-L167
 
 The `(add|change|remove)_file` methods control the set of the input files, where
 each file has an integer id (`FileId`, picked by the client), text (`String`)
@@ -253,13 +253,13 @@ All analyzer information is stored in a salsa database. `Analysis` and
 `AnalysisHost` types are newtype wrappers for [`RootDatabase`] -- a salsa
 database.
 
-[`RootDatabase`]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/ra_ide_api/src/db.rs#L88-L134
+[`RootDatabase`]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/ide_api/src/db.rs#L88-L134
 
 Salsa input queries are defined in [`FilesDatabase`] (which is a part of
 `RootDatabase`). They closely mirror the familiar `AnalysisChange` structure:
 indeed, what `apply_change` does is it sets the values of input queries.
 
-[`FilesDatabase`]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/ra_db/src/input.rs#L150-L174
+[`FilesDatabase`]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/base_db/src/input.rs#L150-L174
 
 ## From text to semantic model
 
@@ -275,7 +275,7 @@ several times, with different sets of `cfg`s enabled. The IDE-specific task of
 mapping source code position into a semantic model is inherently imprecise for
 this reason, and is handled by the [`source_binder`].
 
-[`source_binder`]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/ra_hir/src/source_binder.rs
+[`source_binder`]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/hir/src/source_binder.rs
 
 The semantic interface is declared in the [`code_model_api`] module. Each entity is
 identified by an integer ID and has a bunch of methods which take a salsa database
@@ -283,8 +283,8 @@ as an argument and returns other entities (which are also IDs). Internally, thes
 methods invoke various queries on the database to build the model on demand.
 Here's [the list of queries].
 
-[`code_model_api`]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/ra_hir/src/code_model_api.rs
-[the list of queries]: https://github.com/rust-analyzer/rust-analyzer/blob/7e84440e25e19529e4ff8a66e521d1b06349c6ec/crates/ra_hir/src/db.rs#L20-L106
+[`code_model_api`]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/hir/src/code_model_api.rs
+[the list of queries]: https://github.com/rust-analyzer/rust-analyzer/blob/7e84440e25e19529e4ff8a66e521d1b06349c6ec/crates/hir/src/db.rs#L20-L106
 
 The first step of building the model is parsing the source code.
 
@@ -341,7 +341,7 @@ The algorithm for building a tree of modules is to start with a crate root
 declarations and recursively process child modules. This is handled by the
 [`module_tree_query`], with two slight variations.
 
-[`module_tree_query`]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/ra_hir/src/module_tree.rs#L116-L123
+[`module_tree_query`]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/hir/src/module_tree.rs#L116-L123
 
 First, rust-analyzer builds a module tree for all crates in a source root
 simultaneously. The main reason for this is historical (`module_tree` predates
@@ -364,7 +364,7 @@ the same, we don't have to re-execute [`module_tree_query`]. In fact, we only
 need to re-execute it when we add/remove new files or when we change mod
 declarations.
 
-[`submodules_query`]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/ra_hir/src/module_tree.rs#L41
+[`submodules_query`]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/hir/src/module_tree.rs#L41
 
 We store the resulting modules in a `Vec`-based indexed arena. The indices in
 the arena becomes module IDs. And this brings us to the next topic:
@@ -392,8 +392,8 @@ integers which can "intern" a location and return an integer ID back. The salsa
 database we use includes a couple of [interners]. How to "garbage collect"
 unused locations is an open question.
 
-[`LocationInterner`]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/ra_db/src/loc2id.rs#L65-L71
-[interners]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/ra_hir/src/db.rs#L22-L23
+[`LocationInterner`]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/base_db/src/loc2id.rs#L65-L71
+[interners]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/hir/src/db.rs#L22-L23
 
 For example, we use `LocationInterner` to assign IDs to definitions of functions,
 structs, enums, etc. The location, [`DefLoc`] contains two bits of information:
@@ -407,7 +407,7 @@ using offsets, text ranges or syntax trees as keys and values for queries. What
 we do instead is we store "index" of the item among all of the items of a file
 (so, a positional based ID, but localized to a single file).
 
-[`DefLoc`]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/ra_hir/src/ids.rs#L127-L139
+[`DefLoc`]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/hir/src/ids.rs#L127-L139
 
 One thing we've glossed over for the time being is support for macros. We have
 only proof of concept handling of macros at the moment, but they are extremely
@@ -440,7 +440,7 @@ terms of `HirFileId`! This does not recur infinitely though: any chain of
 `HirFileId`s bottoms out in `HirFileId::FileId`, that is, some source file
 actually written by the user.
 
-[`HirFileId`]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/ra_hir/src/ids.rs#L18-L125
+[`HirFileId`]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/hir/src/ids.rs#L18-L125
 
 Now that we understand how to identify a definition, in a source or in a
 macro-generated file, we can discuss name resolution a bit.
@@ -454,14 +454,14 @@ each module into a position-independent representation which does not change if
 we modify bodies of the items. After that we [loop] resolving all imports until
 we've reached a fixed point.
 
-[lower]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/ra_hir/src/nameres/lower.rs#L113-L117
-[loop]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/ra_hir/src/nameres.rs#L186-L196
+[lower]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/hir/src/nameres/lower.rs#L113-L117
+[loop]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/hir/src/nameres.rs#L186-L196
 
 And, given all our preparation with IDs and a position-independent representation,
 it is satisfying to [test] that typing inside function body does not invalidate
 name resolution results.
 
-[test]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/ra_hir/src/nameres/tests.rs#L376
+[test]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/hir/src/nameres/tests.rs#L376
 
 An interesting fact about name resolution is that it "erases" all of the
 intermediate paths from the imports: in the end, we know which items are defined
@@ -496,10 +496,10 @@ there's an intermediate [projection query] which returns only the first
 position-independent part of the lowering. The result of this query is stable.
 Naturally, name resolution [uses] this stable projection query.
 
-[imports]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/ra_hir/src/nameres/lower.rs#L52-L59
-[`SourceMap`]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/ra_hir/src/nameres/lower.rs#L52-L59
-[projection query]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/ra_hir/src/nameres/lower.rs#L97-L103
-[uses]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/ra_hir/src/query_definitions.rs#L49
+[imports]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/hir/src/nameres/lower.rs#L52-L59
+[`SourceMap`]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/hir/src/nameres/lower.rs#L52-L59
+[projection query]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/hir/src/nameres/lower.rs#L97-L103
+[uses]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/hir/src/query_definitions.rs#L49
 
 ## Type inference
 
@@ -521,10 +521,10 @@ construct a mapping from `ExprId`s to types.
 
 [@flodiebold]: https://github.com/flodiebold
 [#327]: https://github.com/rust-analyzer/rust-analyzer/pull/327
-[lower the AST]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/ra_hir/src/expr.rs
-[positional ID]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/ra_hir/src/expr.rs#L13-L15
-[a source map]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/ra_hir/src/expr.rs#L41-L44
-[type inference]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/ra_hir/src/ty.rs#L1208-L1223
+[lower the AST]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/hir/src/expr.rs
+[positional ID]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/hir/src/expr.rs#L13-L15
+[a source map]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/hir/src/expr.rs#L41-L44
+[type inference]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/hir/src/ty.rs#L1208-L1223
 
 ## Tying it all together: completion
 
@@ -565,11 +565,11 @@ the type to completion.
 [schedule it on the threadpool]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/ra_lsp_server/src/main_loop.rs#L428
 [catch]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/ra_lsp_server/src/main_loop.rs#L436-L442
 [the handler]: https://salsa.zulipchat.com/#narrow/stream/181542-rfcs.2Fsalsa-query-group/topic/design.20next.20steps
-[ask analysis for completion]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/ra_ide_api/src/lib.rs#L439-L444
-[completion implementation]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/ra_ide_api/src/completion.rs#L46-L62
-[`CompletionContext`]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/ra_ide_api/src/completion/completion_context.rs#L14-L37
-["IntelliJ Trick"]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/ra_ide_api/src/completion/completion_context.rs#L72-L75
-[find an ancestor `fn` node]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/ra_ide_api/src/completion/completion_context.rs#L116-L120
-[semantic model]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/ra_ide_api/src/completion/completion_context.rs#L123
-[series of independent completion routines]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/ra_ide_api/src/completion.rs#L52-L59
-[`complete_dot`]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/ra_ide_api/src/completion/complete_dot.rs#L6-L22
+[ask analysis for completion]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/ide_api/src/lib.rs#L439-L444
+[completion implementation]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/ide_api/src/completion.rs#L46-L62
+[`CompletionContext`]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/ide_api/src/completion/completion_context.rs#L14-L37
+["IntelliJ Trick"]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/ide_api/src/completion/completion_context.rs#L72-L75
+[find an ancestor `fn` node]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/ide_api/src/completion/completion_context.rs#L116-L120
+[semantic model]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/ide_api/src/completion/completion_context.rs#L123
+[series of independent completion routines]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/ide_api/src/completion.rs#L52-L59
+[`complete_dot`]: https://github.com/rust-analyzer/rust-analyzer/blob/guide-2019-01/crates/ide_api/src/completion/complete_dot.rs#L6-L22
diff --git a/docs/dev/lsp-extensions.md b/docs/dev/lsp-extensions.md
index 1be01fd88..2e3133449 100644
--- a/docs/dev/lsp-extensions.md
+++ b/docs/dev/lsp-extensions.md
@@ -412,7 +412,13 @@ Reloads project information (that is, re-executes `cargo metadata`).
 
 **Method:** `rust-analyzer/status`
 
-**Notification:** `"loading" | "ready" | "invalid" | "needsReload"`
+**Notification:**
+
+```typescript
+interface StatusParams {
+    status: "loading" | "ready" | "invalid" | "needsReload",
+}
+```
 
 This notification is sent from server to client.
 The client can use it to display persistent status to the user (in modline).
diff --git a/docs/dev/style.md b/docs/dev/style.md
new file mode 100644
index 000000000..44f0956c2
--- /dev/null
+++ b/docs/dev/style.md
@@ -0,0 +1,247 @@
+Our approach to "clean code" is two-fold:
+
+* We generally don't block PRs on style changes.
+* At the same time, all code in rust-analyzer is constantly refactored.
+
+It is explicitly OK for a reviewer to flag only some nits in the PR, and then send a follow-up cleanup PR for things which are easier to explain by example, cc-ing the original author.
+Sending small cleanup PRs (like renaming a single local variable) is encouraged.
+
+# Scale of Changes
+
+Everyone knows that it's better to send small & focused pull requests.
+The problem is, sometimes you *have* to, eg, rewrite the whole compiler, and that just doesn't fit into a set of isolated PRs.
+
+The main things to keep an eye on are the boundaries between various components.
+There are three kinds of changes:
+
+1. Internals of a single component are changed.
+   Specifically, you don't change any `pub` items.
+   A good example here would be an addition of a new assist.
+
+2. API of a component is expanded.
+   Specifically, you add a new `pub` function which wasn't there before.
+   A good example here would be expansion of assist API, for example, to implement lazy assists or assists groups.
+
+3. A new dependency between components is introduced.
+   Specifically, you add a `pub use` reexport from another crate or you add a new line to the `[dependencies]` section of `Cargo.toml`.
+   A good example here would be adding reference search capability to the assists crates.
+
+For the first group, the change is generally merged as long as:
+
+* it works for the happy case,
+* it has tests,
+* it doesn't panic for the unhappy case.
+
+For the second group, the change would be subjected to quite a bit of scrutiny and iteration.
+The new API needs to be right (or at least easy to change later).
+The actual implementation doesn't matter that much.
+It's very important to minimize the amount of changed lines of code for changes of the second kind.
+Often, you start doing a change of the first kind, only to realise that you need to elevate to a change of the second kind.
+In this case, we'll probably ask you to split API changes into a separate PR.
+
+Changes of the third group should be pretty rare, so we don't specify any specific process for them.
+That said, adding an innocent-looking `pub use` is a very simple way to break encapsulation, keep an eye on it!
+
+Note: if you enjoyed this abstract hand-waving about boundaries, you might appreciate
+https://www.tedinski.com/2018/02/06/system-boundaries.html
+
+# Crates.io Dependencies
+
+We try to be very conservative with usage of crates.io dependencies.
+Don't use small "helper" crates (exception: `itertools` is allowed).
+If there's some general reusable bit of code you need, consider adding it to the `stdx` crate.
+
+# Minimal Tests
+
+Most tests in rust-analyzer start with a snippet of Rust code.
+This snippets should be minimal -- if you copy-paste a snippet of real code into the tests, make sure to remove everything which could be removed.
+There are many benefits to this:
+
+* less to read or to scroll past
+* easier to understand what exactly is tested
+* less stuff printed during printf-debugging
+* less time to run test
+
+It also makes sense to format snippets more compactly (for example, by placing enum definitions like `enum E { Foo, Bar }` on a single line),
+as long as they are still readable.
+
+# Order of Imports
+
+Separate import groups with blank lines.
+Use one `use` per crate.
+
+```rust
+mod x;
+mod y;
+
+// First std.
+use std::{ ... }
+
+// Second, external crates (both crates.io crates and other rust-analyzer crates).
+use crate_foo::{ ... }
+use crate_bar::{ ... }
+
+// Then current crate.
+use crate::{}
+
+// Finally, parent and child modules, but prefer `use crate::`.
+use super::{}
+```
+
+Module declarations come before the imports.
+Order them in "suggested reading order" for a person new to the code base.
+
+# Import Style
+
+Qualify items from `hir` and `ast`.
+
+```rust
+// Good
+use syntax::ast;
+
+fn frobnicate(func: hir::Function, strukt: ast::StructDef) {}
+
+// Not as good
+use hir::Function;
+use syntax::ast::StructDef;
+
+fn frobnicate(func: Function, strukt: StructDef) {}
+```
+
+Avoid local `use MyEnum::*` imports.
+
+Prefer `use crate::foo::bar` to `use super::bar`.
+
+# Order of Items
+
+Optimize for the reader who sees the file for the first time, and wants to get a general idea about what's going on.
+People read things from top to bottom, so place most important things first.
+
+Specifically, if all items except one are private, always put the non-private item on top.
+
+Put `struct`s and `enum`s first, functions and impls last.
+
+Do
+
+```rust
+// Good
+struct Foo {
+    bars: Vec<Bar>
+}
+
+struct Bar;
+```
+
+rather than
+
+```rust
+// Not as good
+struct Bar;
+
+struct Foo {
+    bars: Vec<Bar>
+}
+```
+
+# Variable Naming
+
+Use boring and long names for local variables ([yay code completion](https://github.com/rust-analyzer/rust-analyzer/pull/4162#discussion_r417130973)).
+The default name is a lowercased name of the type: `global_state: GlobalState`.
+Avoid ad-hoc acronyms and contractions, but use the ones that exist consistently (`db`, `ctx`, `acc`).
+
+Default names:
+
+* `res` -- "result of the function" local variable
+* `it` -- I don't really care about the name
+* `n_foo` -- number of foos
+* `foo_idx` -- index of `foo`
+
+# Collection types
+
+Prefer `rustc_hash::FxHashMap` and `rustc_hash::FxHashSet` instead of the ones in `std::collections`.
+They use a hasher that's slightly faster and using them consistently will reduce code size by some small amount.
+
+# Preconditions
+
+Express function preconditions in types and force the caller to provide them (rather than checking in callee):
+
+```rust
+// Good
+fn frbonicate(walrus: Walrus) {
+    ...
+}
+
+// Not as good
+fn frobnicate(walrus: Option<Walrus>) {
+    let walrus = match walrus {
+        Some(it) => it,
+        None => return,
+    };
+    ...
+}
+```
+
+# Getters & Setters
+
+If a field can have any value without breaking invariants, make the field public.
+Conversely, if there is an invariant, document it, enforce it in the "constructor" function, make the field private, and provide a getter.
+Never provide setters.
+
+Getters should return borrowed data:
+
+```
+struct Person {
+    // Invariant: never empty
+    first_name: String,
+    middle_name: Option<String>
+}
+
+// Good
+impl Person {
+    fn first_name(&self) -> &str { self.first_name.as_str() }
+    fn middle_name(&self) -> Option<&str> { self.middle_name.as_ref() }
+}
+
+// Not as good
+impl Person {
+    fn first_name(&self) -> String { self.first_name.clone() }
+    fn middle_name(&self) -> &Option<String> { &self.middle_name }
+}
+```
+
+
+# Premature Pessimization
+
+Avoid writing code which is slower than it needs to be.
+Don't allocate a `Vec` where an iterator would do, don't allocate strings needlessly.
+
+```rust
+// Good
+use itertools::Itertools;
+
+let (first_word, second_word) = match text.split_ascii_whitespace().collect_tuple() {
+    Some(it) => it,
+    None => return,
+}
+
+// Not as good
+let words = text.split_ascii_whitespace().collect::<Vec<_>>();
+if words.len() != 2 {
+    return
+}
+```
+
+# Documentation
+
+For `.md` and `.adoc` files, prefer a sentence-per-line format, don't wrap lines.
+If the line is too long, you want to split the sentence in two :-)
+
+# Commit Style
+
+We don't have specific rules around git history hygiene.
+Maintaining clean git history is strongly encouraged, but not enforced.
+Use rebase workflow, it's OK to rewrite history during PR review process.
+After you are happy with the state of the code, please use [interactive rebase](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History) to squash fixup commits.
+
+Avoid @mentioning people in commit messages and pull request descriptions(they are added to commit message by bors).
+Such messages create a lot of duplicate notification traffic during rebases.
diff --git a/docs/dev/syntax.md b/docs/dev/syntax.md
index d4bc4b07c..c08062ef4 100644
--- a/docs/dev/syntax.md
+++ b/docs/dev/syntax.md
@@ -11,7 +11,7 @@ The things described are implemented in two places
 * [rowan](https://github.com/rust-analyzer/rowan/tree/v0.9.0) -- a generic library for rowan syntax trees.
 * [ra_syntax](https://github.com/rust-analyzer/rust-analyzer/tree/cf5bdf464cad7ceb9a67e07985a3f4d3799ec0b6/crates/ra_syntax) crate inside rust-analyzer which wraps `rowan` into rust-analyzer specific API.
   Nothing in rust-analyzer except this crate knows about `rowan`.
-* [ra_parser](https://github.com/rust-analyzer/rust-analyzer/tree/cf5bdf464cad7ceb9a67e07985a3f4d3799ec0b6/crates/ra_parser) crate parses input tokens into an `ra_syntax` tree
+* [parser](https://github.com/rust-analyzer/rust-analyzer/tree/cf5bdf464cad7ceb9a67e07985a3f4d3799ec0b6/crates/parser) crate parses input tokens into an `ra_syntax` tree
 
 ## Design Goals
 
@@ -74,7 +74,7 @@ Points of note:
 * The original text can be recovered by concatenating the texts of all tokens in order.
 * Accessing a child of particular type (for example, parameter list of a function) generally involves linerary traversing the children, looking for a specific `kind`.
 * Modifying the tree is roughly `O(depth)`.
-  We don't make special efforts to guarantree that the depth is not liner, but, in practice, syntax trees are branchy and shallow.
+  We don't make special efforts to guarantee that the depth is not linear, but, in practice, syntax trees are branchy and shallow.
 * If mandatory (grammar wise) node is missing from the input, it's just missing from the tree.
 * If an extra erroneous input is present, it is wrapped into a node with `ERROR` kind, and treated just like any other node.
 * Parser errors are not a part of syntax tree.