diff --git a/crates/ruff_server/README.md b/crates/ruff_server/README.md index beccb4bdb12d6..4bcd8e9635476 100644 --- a/crates/ruff_server/README.md +++ b/crates/ruff_server/README.md @@ -9,8 +9,11 @@ files in your editor's workspace, and will refresh its in-memory configuration w We have specific setup instructions depending on your editor. If you don't see your editor on this list and would like a setup guide, please open an issue. -- Visual Studio Code: Install the [Ruff extension from the VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=charliermarsh.ruff). The language server used by the extension will be, by default, the one in your actively-installed `ruff` binary. If you don't have `ruff` installed and haven't provided a path to the extension, it comes with a bundled `ruff` version that it will use instead. Since the new Ruff language server has not yet been stabilized, you will need to use the pre-release version of the extension and enable the `Experimental Server` setting. +- Visual Studio Code: Install the [Ruff extension from the VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=charliermarsh.ruff). **As this server is still in beta, you will need to enable the `Native Server` extension setting**. The language server used by the extension will be, by default, the one in your actively-installed `ruff` binary. If you don't have `ruff` installed and haven't provided a path to the extension, it comes with a bundled `ruff` version that it will use instead. - Neovim: See the [Neovim setup guide](docs/setup/NEOVIM.md). +- Helix: See the [Helix setup guide](docs/setup//HELIX.md). + +If you are transferring your configuration from `ruff-lsp`, regardless of editor, there are several settings which have changed or are no longer available which you should be aware of. See the [migration guide](docs/MIGRATION.md) for more details. ### Contributing diff --git a/crates/ruff_server/docs/MIGRATION.md b/crates/ruff_server/docs/MIGRATION.md new file mode 100644 index 0000000000000..8e14bb20fca0b --- /dev/null +++ b/crates/ruff_server/docs/MIGRATION.md @@ -0,0 +1,44 @@ +## Migrating From `ruff-lsp` + +`ruff server`'s configuration is significantly different from `ruff-lsp`, and as such you may need to update your existing configuration. + +> \[!NOTE\] +> +> The VS Code extension settings have documentation that will tell you whether or not the beta server (`ruff server`) supports a given setting. +> This migration guide may be more useful for the editors that do not have explicitly documented settings for the language server, +> such as Helix or Neovim. + +### Unsupported Settings + +Several `ruff-lsp` settings are not supported by `ruff server`. These are, as follows: + +- `format.args` +- `ignoreStandardLibrary` +- `interpreter` +- `lint.args` +- `lint.run` +- `logLevel` +- `path` + +Note that some of these settings, like `interpreter` and `path`, are still accepted by the VS Code extension. `path`, in particular, can be used to set the ruff binary +used to run `ruff server`. But the server itself will no longer accept these as settings. + +### New Settings + +`ruff server` introduces several new settings that `ruff-lsp` does not have. These are, as follows: + +- `configuration`: This is a path to a `ruff.toml` or `pyproject.toml` file to use for configuration. By default, Ruff will discover configuration for each project from the filesystem, mirroring the behavior of the Ruff CLI. +- `configurationPreference`: Used to specify how you want to resolve server settings with local file configuration. The following values are available: + - `"editorFirst"`: The default strategy - configuration set in the server settings takes priority over configuration set in `.toml` files. + - `"filesystemFirst"`: An alternative strategy - configuration set in `.toml` files takes priority over configuration set in the server settings. + - `"editorOnly"`: An alternative strategy - configuration set in `.toml` files is ignored entirely. +- `exclude`: Paths for the linter and formatter to ignore. See [the documentation](https://docs.astral.sh/ruff/settings/#exclude) for more details. +- `format.preview`: Enables [preview mode](https://docs.astral.sh/ruff/settings/#format_preview) for the formatter; enables unstable formatting. +- `lineLength`: The [line length](https://docs.astral.sh/ruff/settings/#line-length) used by the formatter and linter. +- `lint.select`: The rule codes to enable. Use `ALL` to enable all rules. See [the documentation](https://docs.astral.sh/ruff/settings/#lint_select) for more details. +- `lint.extendSelect`: Enables additional rule codes on top of existing configuration, instead of overriding it. Use `ALL` to enable all rules. +- `lint.ignore`: Sets rule codes to disable. See [the documentation](https://docs.astral.sh/ruff/settings/#lint_ignore) for more details. +- `lint.preview`: Enables [preview mode](https://docs.astral.sh/ruff/settings/#lint_preview) for the linter; enables unstable rules and fixes. + +Several of these new settings are replacements for the now-unsupported `format.args` and `lint.args`. For example, if you have been passing in `--select=` +to `lint.args`, you can migrate to the new server by using `lint.select` with a value of `[""]`.