diff --git a/docs/editors/migration.md b/docs/editors/migration.md index 4be54469c8..194e6f21a9 100644 --- a/docs/editors/migration.md +++ b/docs/editors/migration.md @@ -1,16 +1,17 @@ # Migrating from `ruff-lsp` -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. +[`ruff-lsp`][ruff-lsp] is the [Language Server Protocol] implementation for Ruff to power the editor +integrations. It is written in Python and is a separate package from Ruff itself. The **native +server**, however, is the [Language Server Protocol] 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`][ruff-lsp] to the native server. !!! note - 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. + The native server was first introduced in Ruff version `0.3.5`. It was marked as [beta in + version `0.4.5`](https://astral.sh/blog/ruff-v0.4.5) and officially [stabilized in version + `0.5.3`](https://github.com/astral-sh/ruff/releases/tag/0.5.3). It is recommended to use the + latest version of Ruff to ensure the best experience. The migration process involves any or all of the following: @@ -18,32 +19,36 @@ The migration process involves any or all of the following: 1. [Remove settings](#removed-settings) that are no longer supported 1. Update the `ruff` version +Read on to learn more about the unsupported or new settings, or jump to the [examples](#examples) +that enumerate some of the common settings and how to migrate them. + ## Unsupported Settings -The following [`ruff-lsp`](https://github.com/astral-sh/ruff-lsp) settings are not supported by `ruff server`: +The following [`ruff-lsp`][ruff-lsp] settings are not supported by the native server: -- `lint.run`: This setting is no longer relevant for the native language server, which runs on every - 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). +- [`lint.run`](settings.md#lintrun): This setting is no longer relevant for the native language + server, which runs on every keystroke by default. +- [`lint.args`](settings.md#lintargs), [`format.args`](settings.md#formatargs): These settings have + been replaced by more granular settings in the native server like [`lint.select`](settings.md#select), + [`format.preview`](settings.md#format_preview), etc. along with the ability to override any + configuration using the [`configuration`](settings.md#configuration) setting. -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: +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 each is 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: +Additionally, the following settings are not supported by the native server and should be removed: -- `ignoreStandardLibrary` -- `showNotifications` +- [`ignoreStandardLibrary`](settings.md#ignorestandardlibrary) +- [`showNotifications`](settings.md#shownotifications) ## New Settings -`ruff server` introduces several new settings that [`ruff-lsp`](https://github.com/astral-sh/ruff-lsp) does not have. These are, as follows: +The native server introduces several new settings that [`ruff-lsp`][ruff-lsp] does not have: - [`configuration`](settings.md#configuration) - [`configurationPreference`](settings.md#configurationpreference) @@ -55,44 +60,96 @@ Additionally, the following settings are not supported by the native server, the - [`lint.ignore`](settings.md#ignore) - [`lint.preview`](settings.md#lint_preview) -Several of these new settings are replacements for the now-unsupported `format.args` and `lint.args`. For example, if -you've been passing `--select=` to `lint.args`, you can migrate to the new server by using `lint.select` with a -value of `[""]`. - ## Examples -Let's say you have these settings in VS Code: +All of the examples mentioned below are only valid for the [VS Code extension]. For other editors, +please refer to their respective documentation sections in the [settings](settings.md) page. + +### Configuration file + +If you've been providing a configuration file as shown below: ```json { - "ruff.lint.args": "--select=E,F --line-length 80 --config ~/.config/custom_ruff_config.toml" + "ruff.lint.args": "--config ~/.config/custom_ruff_config.toml", + "ruff.format.args": "--config ~/.config/custom_ruff_config.toml" } ``` -After enabling the native server, you can migrate your settings like so: +You can migrate to the new server by using the [`configuration`](settings.md#configuration) setting +like below which will apply the configuration to both the linter and the formatter: + +```json +{ + "ruff.configuration": "~/.config/custom_ruff_config.toml" +} +``` + +### `lint.args` + +If you're providing the linter flags by using `ruff.lint.args` like so: + +```json +{ + "ruff.lint.args": "--select=E,F --unfixable=F401 --unsafe-fixes" +} +``` + +You can migrate to the new server by using the [`lint.select`](settings.md#select) and +[`configuration`](settings.md#configuration) setting like so: + +```json +{ + "ruff.lint.select": ["E", "F"], + "ruff.configuration": { + "unsafe-fixes": true, + "lint": { + "unfixable": ["F401"] + } + } +} +``` + +The following options can be set directly in the editor settings: + +- [`lint.select`](settings.md#select) +- [`lint.extendSelect`](settings.md#extendselect) +- [`lint.ignore`](settings.md#ignore) +- [`lint.preview`](settings.md#lint_preview) + +The remaining options can be set using the [`configuration`](settings.md#configuration) setting. + +### `format.args` + +If you're also providing formatter flags by using `ruff.format.args` like so: + +```json +{ + "ruff.format.args": "--line-length 80 --config='format.quote-style=double'" +} +``` + +You can migrate to the new server by using the [`lineLength`](settings.md#linelength) and +[`configuration`](settings.md#configuration) setting like so: ```json { - "ruff.configuration": "~/.config/custom_ruff_config.toml", "ruff.lineLength": 80, - "ruff.lint.select": ["E", "F"] + "ruff.configuration": { + "format": { + "quote-style": "double" + } + } } ``` -Similarly, let's say you have these settings in Helix: +The following options can be set directly in the editor settings: -```toml -[language-server.ruff.config.lint] -args = "--select=E,F --line-length 80 --config ~/.config/custom_ruff_config.toml" -``` +- [`lineLength`](settings.md#linelength) +- [`format.preview`](settings.md#format_preview) -These can be migrated like so: +The remaining options can be set using the [`configuration`](settings.md#configuration) setting. -```toml -[language-server.ruff.config] -configuration = "~/.config/custom_ruff_config.toml" -lineLength = 80 - -[language-server.ruff.config.lint] -select = ["E", "F"] -``` +[language server protocol]: https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/ +[ruff-lsp]: https://github.com/astral-sh/ruff-lsp +[vs code extension]: https://github.com/astral-sh/ruff-vscode