From e0d00ed25c538553e3437e999076add05d8d1c9c Mon Sep 17 00:00:00 2001 From: Dhruv Manilawala Date: Mon, 10 Feb 2025 14:50:55 +0530 Subject: [PATCH] Improve migration document --- docs/editors/migration.md | 43 ++++++++++++++++++++++++++------------- 1 file changed, 29 insertions(+), 14 deletions(-) diff --git a/docs/editors/migration.md b/docs/editors/migration.md index 57486fba9ba5c..4be54469c80fe 100644 --- a/docs/editors/migration.md +++ b/docs/editors/migration.md @@ -1,34 +1,49 @@ # Migrating from `ruff-lsp` -While `ruff server` supports the same feature set as [`ruff-lsp`](https://github.com/astral-sh/ruff-lsp), migrating to -`ruff server` may require changes to your Ruff or language server configuration. +To provide some context, [`ruff-lsp`](https://github.com/astral-sh/ruff-lsp) is the LSP implementation for Ruff to power the editor +integrations which is written in Python and is a separate package from Ruff itself. The **native +server** is the LSP implementation which is written in Rust and is available under the `ruff server` +command. This guide is intended to help users migrate from +[`ruff-lsp`](https://github.com/astral-sh/ruff-lsp) to the native server. !!! note - The [VS Code extension](https://github.com/astral-sh/ruff-vscode) settings include documentation to indicate which - settings are supported by `ruff server`. As such, this migration guide is primarily targeted at editors that lack - explicit documentation for `ruff server` settings, such as Helix or Neovim. + The native server was first introduced in Ruff version `0.3.5`. It was marked as beta in version + `0.4.5` and officially stabilized in version `0.5.3`. It is recommended to use the latest + version of Ruff to ensure the best experience. -Refer to the [setup guide](setup.md) for instructions on how to configure your editor to use `ruff server`. +The migration process involves any or all of the following: + +1. Migrate [deprecated settings](#unsupported-settings) to the [new settings](#new-settings) +1. [Remove settings](#removed-settings) that are no longer supported +1. Update the `ruff` version ## Unsupported Settings -Several `ruff-lsp` settings are not supported by `ruff server`. These are, as follows: +The following [`ruff-lsp`](https://github.com/astral-sh/ruff-lsp) settings are not supported by `ruff server`: - `lint.run`: This setting is no longer relevant for the native language server, which runs on every - keystroke by default + keystroke by default. - `lint.args`, `format.args`: These settings have been replaced by more granular settings in `ruff server` like [`lint.select`](settings.md#select), [`format.preview`](settings.md#format_preview), - etc. along with the ability to provide a default configuration file using - [`configuration`](settings.md#configuration) -- [`path`](settings.md#path), [`interpreter`](settings.md#interpreter): These settings are no longer - accepted by the language server but are still used by the VS Code extension. Refer to their - respective documentation for more information on how it's being used by the extension. + etc. along with the ability to provide a default configuration file using [`configuration`](settings.md#configuration). + +The following settings are not accepted by the language server but are still used by the VS Code +extension. Refer to their respective documentation for more information on how it's being used by +the extension: + +- [`path`](settings.md#path) +- [`interpreter`](settings.md#interpreter) + +## Removed Settings + +Additionally, the following settings are not supported by the native server, they should be removed: + - `ignoreStandardLibrary` - `showNotifications` ## New Settings -`ruff server` introduces several new settings that `ruff-lsp` does not have. These are, as follows: +`ruff server` introduces several new settings that [`ruff-lsp`](https://github.com/astral-sh/ruff-lsp) does not have. These are, as follows: - [`configuration`](settings.md#configuration) - [`configurationPreference`](settings.md#configurationpreference)