mirror of https://github.com/astral-sh/ruff
Update migration guide with the new `ruff.configuration` (#16567)
## Summary This PR updates the migration guide to use the new `ruff.configuration` settings update to provide a better experience. ### Preview <details><summary>Migration page screenshot</summary> <p>  </p> </details>
This commit is contained in:
Dhruv Manilawala
GitHub
parent
36d12cea47
commit
f19cb86c5d
|
|
@ -1,16 +1,17 @@
|
||||||
# Migrating from `ruff-lsp`
|
# 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
|
[`ruff-lsp`][ruff-lsp] is the [Language Server Protocol] implementation for Ruff to power the editor
|
||||||
integrations which is written in Python and is a separate package from Ruff itself. The **native
|
integrations. It 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`
|
server**, however, is the [Language Server Protocol] implementation which is **written in Rust** and
|
||||||
command. This guide is intended to help users migrate from
|
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] to the native server.
|
||||||
|
|
||||||
!!! note
|
!!! note
|
||||||
|
|
||||||
The native server was first introduced in Ruff version `0.3.5`. It was marked as beta in version
|
The native server was first introduced in Ruff version `0.3.5`. It was marked as [beta in
|
||||||
`0.4.5` and officially stabilized in version `0.5.3`. It is recommended to use the latest
|
version `0.4.5`](https://astral.sh/blog/ruff-v0.4.5) and officially [stabilized in version
|
||||||
version of Ruff to ensure the best experience.
|
`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:
|
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. [Remove settings](#removed-settings) that are no longer supported
|
||||||
1. Update the `ruff` version
|
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
|
## 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
|
- [`lint.run`](settings.md#lintrun): This setting is no longer relevant for the native language
|
||||||
keystroke by default.
|
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),
|
- [`lint.args`](settings.md#lintargs), [`format.args`](settings.md#formatargs): These settings have
|
||||||
etc. along with the ability to provide a default configuration file using [`configuration`](settings.md#configuration).
|
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
|
The following settings are not accepted by the language server but are still used by the [VS Code extension].
|
||||||
extension. Refer to their respective documentation for more information on how it's being used by
|
Refer to their respective documentation for more information on how each is used by the extension:
|
||||||
the extension:
|
|
||||||
|
|
||||||
- [`path`](settings.md#path)
|
- [`path`](settings.md#path)
|
||||||
- [`interpreter`](settings.md#interpreter)
|
- [`interpreter`](settings.md#interpreter)
|
||||||
|
|
||||||
## Removed Settings
|
## 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`
|
- [`ignoreStandardLibrary`](settings.md#ignorestandardlibrary)
|
||||||
- `showNotifications`
|
- [`showNotifications`](settings.md#shownotifications)
|
||||||
|
|
||||||
## New Settings
|
## 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)
|
- [`configuration`](settings.md#configuration)
|
||||||
- [`configurationPreference`](settings.md#configurationpreference)
|
- [`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.ignore`](settings.md#ignore)
|
||||||
- [`lint.preview`](settings.md#lint_preview)
|
- [`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=<RULES>` to `lint.args`, you can migrate to the new server by using `lint.select` with a
|
|
||||||
value of `["<RULES>"]`.
|
|
||||||
|
|
||||||
## Examples
|
## 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
|
```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
|
```json
|
||||||
{
|
{
|
||||||
"ruff.configuration": "~/.config/custom_ruff_config.toml",
|
|
||||||
"ruff.lineLength": 80,
|
"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
|
- [`lineLength`](settings.md#linelength)
|
||||||
[language-server.ruff.config.lint]
|
- [`format.preview`](settings.md#format_preview)
|
||||||
args = "--select=E,F --line-length 80 --config ~/.config/custom_ruff_config.toml"
|
|
||||||
```
|
|
||||||
|
|
||||||
These can be migrated like so:
|
The remaining options can be set using the [`configuration`](settings.md#configuration) setting.
|
||||||
|
|
||||||
```toml
|
[language server protocol]: https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/
|
||||||
[language-server.ruff.config]
|
[ruff-lsp]: https://github.com/astral-sh/ruff-lsp
|
||||||
configuration = "~/.config/custom_ruff_config.toml"
|
[vs code extension]: https://github.com/astral-sh/ruff-vscode
|
||||||
lineLength = 80
|
|
||||||
|
|
||||||
[language-server.ruff.config.lint]
|
|
||||||
select = ["E", "F"]
|
|
||||||
```
|
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue