document upgrade process

closes #1615

2 files changed, 5 insertions, 0 deletions

diff --git a/docs/dev/README.md b/docs/dev/README.md
index 74c58d4af..0db3e731e 100644
--- a/docs/dev/README.md
+++ b/docs/dev/README.md
@@ -116,6 +116,8 @@ Due to the requirements of running the tests inside VS Code they are **not run
 on CI**. When making changes to the extension please ensure the tests are not
 broken locally before opening a Pull Request.
 
+To install **only** the VS Code extension, use `cargo install-ra --client-code`.
+
 # Logging
 
 Logging is done by both rust-analyzer and VS Code, so it might be tricky to
diff --git a/docs/user/README.md b/docs/user/README.md
index 122388a42..a5e17f604 100644
--- a/docs/user/README.md
+++ b/docs/user/README.md
@@ -58,6 +58,9 @@ Beyond basic LSP features, there are some extension commands which you can
 invoke via <kbd>Ctrl+Shift+P</kbd> or bind to a shortcut. See [./features.md](./features.md)
 for details.
 
+For updates, pull the latest changes from the master branch, run `cargo install-ra` again, and **restart** VS Code instance.
+See https://github.com/microsoft/vscode/issues/72308[microsoft/vscode#72308] for why a full restart is needed.
+
 ### Settings
 
 * `rust-analyzer.highlightingOn`: enables experimental syntax highlighting