5 files changed, 113 insertions, 43 deletions

diff --git a/docs/dev/README.md b/docs/dev/README.md
index 9c0eb1358..16b23adc6 100644
--- a/docs/dev/README.md
+++ b/docs/dev/README.md
@@ -208,20 +208,26 @@ Release process is handled by `release`, `dist` and `promote` xtasks, `release`
 
 Additionally, it assumes that remote for `rust-analyzer` is called `upstream` (I use `origin` to point to my fork).
 
+`release` calls the GitHub API calls to scrape pull request comments and categorize them in the changelog.
+This step uses the `curl` and `jq` applications, which need to be available in `PATH`.
+Finally, you need to obtain a GitHub personal access token and set the `GITHUB_TOKEN` environment variable.
+
 Release steps:
 
-1. Inside rust-analyzer, run `cargo xtask release`. This will:
+1. Set the `GITHUB_TOKEN` environment variable.
+2. 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`
-2. While the release is in progress, fill in the changelog
-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.
+   * call the GitHub API for PR details
+   * create a new changelog in `rust-analyzer.github.io`
+3. While the release is in progress, fill in the changelog
+4. Commit & push the changelog
+5. Tweet
+6. 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.
 
 If the GitHub Actions release fails because of a transient problem like a timeout, you can re-run the job from the Actions console.
@@ -229,18 +235,27 @@ If it fails because of something that needs to be fixed, remove the release tag
 Make sure to remove the new changelog post created when running `cargo xtask release` a second time.
 
 We release "nightly" every night automatically and promote the latest nightly to "stable" manually, every week.
+
 We don't do "patch" releases, unless something truly egregious comes up.
+To do a patch release, cherry-pick the fix on top of the current `release` branch and push the branch.
+There's no need to write a changelog for a patch release, it's OK to include the notes about the fix into the next weekly one.
+Note: we tag releases by dates, releasing a patch release on the same day should work (by overwriting a tag), but I am not 100% sure.
 
 ## Permissions
 
 There are three sets of people with extra permissions:
 
-* rust-analyzer GitHub organization **admins** (which include current t-compiler leads).
+* rust-analyzer GitHub organization [**admins**](https://github.com/orgs/rust-analyzer/people?query=role:owner) (which include current t-compiler leads).
   Admins have full access to the org.
-* **review** team in the organization.
+* [**review**](https://github.com/orgs/rust-analyzer/teams/review) team in the organization.
   Reviewers have `r+` access to all of organization's repositories and publish rights on crates.io.
   They also have direct commit access, but all changes should via bors queue.
   It's ok to self-approve if you think you know what you are doing!
   bors should automatically sync the permissions.
-* **triage** team in the organization.
+  Feel free to request a review or assign any PR to a reviewer with the relevant expertise to bring the work to their attention.
+  Don't feel pressured to review assigned PRs though.
+  If you don't feel like reviewing for whatever reason, someone else will pick the review up!
+* [**triage**](https://github.com/orgs/rust-analyzer/teams/triage) team in the organization.
   This team can label and close issues.
+
+Note that at the time being you need to be a member of the org yourself to view the links.
diff --git a/docs/dev/lsp-extensions.md b/docs/dev/lsp-extensions.md
index a46121bb2..f0f981802 100644
--- a/docs/dev/lsp-extensions.md
+++ b/docs/dev/lsp-extensions.md
@@ -1,8 +1,8 @@
 <!---
-lsp_ext.rs hash: faae991334a151d0
+lsp_ext.rs hash: 28a9d5a24b7ca396
 
 If you need to change the above hash to make the test pass, please check if you
-need to adjust this doc as well and ping this  issue:
+need to adjust this doc as well and ping this issue:
 
   https://github.com/rust-analyzer/rust-analyzer/issues/4604
 
@@ -46,6 +46,7 @@ If this capability is set, `WorkspaceEdit`s returned from `codeAction` requests
 ```typescript
 interface SnippetTextEdit extends TextEdit {
     insertTextFormat?: InsertTextFormat;
+    annotationId?: ChangeAnnotationIdentifier;
 }
 ```
 
@@ -421,7 +422,7 @@ Reloads project information (that is, re-executes `cargo metadata`).
 
 ## Server Status
 
-**Experimental Client Capability:** `{ "serverStatus": boolean }`
+**Experimental Client Capability:** `{ "serverStatusNotification": boolean }`
 
 **Method:** `experimental/serverStatus`
 
@@ -432,11 +433,13 @@ interface ServerStatusParams {
     /// `ok` means that the server is completely functional.
     ///
     /// `warning` means that the server is partially functional.
-    /// It can server requests, but some results might be wrong due to,
-    /// for example, some missing dependencies.
+    /// It can answer correctly to most requests, but some results
+    /// might be wrong due to, for example, some missing dependencies.
     ///
     /// `error` means that the server is not functional. For example,
-    /// there's a fatal build configuration problem.
+    /// there's a fatal build configuration problem. The server might
+    /// still give correct answers to simple requests, but most results
+    /// will be incomplete or wrong.
     health: "ok" | "warning" | "error",
     /// Is there any pending background work which might change the status?
     /// For example, are dependencies being downloaded?
@@ -450,6 +453,9 @@ This notification is sent from server to client.
 The client can use it to display *persistent* status to the user (in modline).
 It is similar to the `showMessage`, but is intended for stares rather than point-in-time events.
 
+Note that this functionality is intended primarily to inform the end user about the state of the server.
+In particular, it's valid for the client to completely ignore this extension.
+Clients are discouraged from but are allowed to use the `health` status to decide if it's worth sending a request to the server.
 
 ## Syntax Tree
 
@@ -620,7 +626,7 @@ This request is sent from client to server to move item under cursor or selectio
 
 **Request:** `MoveItemParams`
 
-**Response:** `TextDocumentEdit | null`
+**Response:** `SnippetTextEdit[]`
 
 ```typescript
 export interface MoveItemParams {
diff --git a/docs/dev/style.md b/docs/dev/style.md
index 468dedff2..6ab60b50e 100644
--- a/docs/dev/style.md
+++ b/docs/dev/style.md
@@ -83,8 +83,19 @@ This makes it easier to prepare a changelog.
 
 If the change adds a new user-visible functionality, consider recording a GIF with [peek](https://github.com/phw/peek) and pasting it into the PR description.
 
+To make writing the release notes easier, you can mark a pull request as a feature, fix, internal change, or minor.
+Minor changes are excluded from the release notes, while the other types are distributed in their corresponding sections.
+There are two ways to mark this:
+
+* use a `feat: `, `feature: `, `fix: `, `internal: ` or `minor: ` prefix in the PR title
+* write `changelog [feature|fix|internal|skip] [description]` in a comment or in the PR description; the description is optional, and will replace the title if included.
+
+These comments don't have to be added by the PR author.
+Editing a comment or the PR description or title is also fine, as long as it happens before the release.
+
 **Rationale:** clean history is potentially useful, but rarely used.
 But many users read changelogs.
+Including a description and GIF suitable for the changelog means less work for the maintainers on the release day.
 
 ## Clippy
 
@@ -152,6 +163,16 @@ Do not reuse marks between several tests.
 
 **Rationale:** marks provide an easy way to find the canonical test for each bit of code.
 This makes it much easier to understand.
+More than one mark per test / code branch doesn't add significantly to understanding.
+
+## `#[should_panic]`
+
+Do not use `#[should_panic]` tests.
+Instead, explicitly check for `None`, `Err`, etc.
+
+**Rationale:** `#[should_panic]` is a tool for library authors, to makes sure that API does not fail silently, when misused.
+`rust-analyzer` is not a library, we don't need to test for API misuse, and we have to handle any user input without panics.
+Panic messages in the logs from the `#[should_panic]` tests are confusing.
 
 ## Function Preconditions
 
diff --git a/docs/user/generated_config.adoc b/docs/user/generated_config.adoc
index e0ee35b4e..e28423e99 100644
--- a/docs/user/generated_config.adoc
+++ b/docs/user/generated_config.adoc
@@ -147,6 +147,12 @@ have more false positives than usual.
 --
 List of rust-analyzer diagnostics to disable.
 --
+[[rust-analyzer.diagnostics.remapPrefix]]rust-analyzer.diagnostics.remapPrefix (default: `{}`)::
++
+--
+Map of prefixes to be substituted when parsing diagnostic file paths.
+This should be the reverse mapping of what is passed to `rustc` as `--remap-path-prefix`.
+--
 [[rust-analyzer.diagnostics.warningsAsHint]]rust-analyzer.diagnostics.warningsAsHint (default: `[]`)::
 +
 --
diff --git a/docs/user/manual.adoc b/docs/user/manual.adoc
index 7510736e9..58722aaa3 100644
--- a/docs/user/manual.adoc
+++ b/docs/user/manual.adoc
@@ -429,24 +429,32 @@ However, if you use some other build system, you'll have to describe the structu
 [source,TypeScript]
 ----
 interface JsonProject {
-    /// Path to the directory with *source code* of sysroot crates.
+    /// Path to the directory with *source code* of
+    /// sysroot crates.
+    ///
+    /// It should point to the directory where std,
+    /// core, and friends can be found:
     ///
-    /// It should point to the directory where std, core, and friends can be found:
     /// https://github.com/rust-lang/rust/tree/master/library.
     ///
-    /// If provided, rust-analyzer automatically adds dependencies on sysroot
-    /// crates. Conversely, if you omit this path, you can specify sysroot
-    /// dependencies yourself and, for example, have several different "sysroots" in
-    /// one graph of crates.
+    /// If provided, rust-analyzer automatically adds
+    /// dependencies on sysroot crates. Conversely,
+    /// if you omit this path, you can specify sysroot
+    /// dependencies yourself and, for example, have
+    /// several different "sysroots" in one graph of
+    /// crates.
     sysroot_src?: string;
-    /// The set of crates comprising the current project.
-    /// Must include all transitive dependencies as well as sysroot crate (libstd, libcore and such).
+    /// The set of crates comprising the current
+    /// project. Must include all transitive
+    /// dependencies as well as sysroot crate (libstd,
+    /// libcore and such).
     crates: Crate[];
 }
 
 interface Crate {
-    /// Optional crate name used for display purposes, without affecting semantics.
-    /// See the `deps` key for semantically-significant crate names.
+    /// Optional crate name used for display purposes,
+    /// without affecting semantics. See the `deps`
+    /// key for semantically-significant crate names.
     display_name?: string;
     /// Path to the root module of the crate.
     root_module: string;
@@ -454,45 +462,59 @@ interface Crate {
     edition: "2015" | "2018" | "2021";
     /// Dependencies
     deps: Dep[];
-    /// Should this crate be treated as a member of current "workspace".
+    /// Should this crate be treated as a member of
+    /// current "workspace".
     ///
-    /// By default, inferred from the `root_module` (members are the crates which reside
-    /// inside the directory opened in the editor).
+    /// By default, inferred from the `root_module`
+    /// (members are the crates which reside inside
+    /// the directory opened in the editor).
     ///
-    /// Set this to `false` for things like standard library and 3rd party crates to
-    /// enable performance optimizations (rust-analyzer assumes that non-member crates
-    /// don't change).
+    /// Set this to `false` for things like standard
+    /// library and 3rd party crates to enable
+    /// performance optimizations (rust-analyzer
+    /// assumes that non-member crates don't change).
     is_workspace_member?: boolean;
-    /// Optionally specify the (super)set of `.rs` files comprising this crate.
+    /// Optionally specify the (super)set of `.rs`
+    /// files comprising this crate.
     ///
-    /// By default, rust-analyzer assumes that only files under `root_module.parent` can belong to a crate.
-    /// `include_dirs` are included recursively, unless a subdirectory is in `exclude_dirs`.
+    /// By default, rust-analyzer assumes that only
+    /// files under `root_module.parent` can belong
+    /// to a crate. `include_dirs` are included
+    /// recursively, unless a subdirectory is in
+    /// `exclude_dirs`.
     ///
     /// Different crates can share the same `source`.
     ///
-    /// If two crates share an `.rs` file in common, they *must* have the same `source`.
-    /// rust-analyzer assumes that files from one source can't refer to files in another source.
+    /// If two crates share an `.rs` file in common,
+    /// they *must* have the same `source`.
+    /// rust-analyzer assumes that files from one
+    /// source can't refer to files in another source.
     source?: {
         include_dirs: string[],
         exclude_dirs: string[],
     },
-    /// The set of cfgs activated for a given crate, like `["unix", "feature=\"foo\"", "feature=\"bar\""]`.
+    /// The set of cfgs activated for a given crate, like
+    /// `["unix", "feature=\"foo\"", "feature=\"bar\""]`.
     cfg: string[];
     /// Target triple for this Crate.
     ///
-    /// Used when running `rustc --print cfg` to get target-specific cfgs.
+    /// Used when running `rustc --print cfg`
+    /// to get target-specific cfgs.
     target?: string;
-    /// Environment variables, used for the `env!` macro
+    /// Environment variables, used for
+    /// the `env!` macro
     env: : { [key: string]: string; },
 
-    /// For proc-macro crates, path to compiles proc-macro (.so file).
+    /// For proc-macro crates, path to compiled
+    /// proc-macro (.so file).
     proc_macro_dylib_path?: string;
 }
 
 interface Dep {
     /// Index of a crate in the `crates` array.
     crate: number,
-    /// Name as should appear in the (implicit) `extern crate name` declaration.
+    /// Name as should appear in the (implicit)
+    /// `extern crate name` declaration.
     name: string,
 }
 ----
@@ -541,7 +563,7 @@ include::./generated_assists.adoc[]
 == Diagnostics
 
 While most errors and warnings provided by rust-analyzer come from the `cargo check` integration, there's a growing number of diagnostics implemented using rust-analyzer's own analysis.
-These diagnostics don't respect `#[allow]` or `#[deny]` attributes yet, but can be turned off using the `rust-analyzer.diagnostics.enable`, `rust-analyzer.diagnostics.enableExperimental` or `rust-analyzer.diagnostics.disabled` settings.
+Some of these diagnostics don't respect `\#[allow]` or `\#[deny]` attributes yet, but can be turned off using the `rust-analyzer.diagnostics.enable`, `rust-analyzer.diagnostics.enableExperimental` or `rust-analyzer.diagnostics.disabled` settings.
 
 include::./generated_diagnostic.adoc[]