Update documentation for ruff server with new migration guide (#11499)

## Summary

Introduces a migration guide from `ruff-lsp` to `ruff server` and makes
small updates to the `README.md`.

Author: snowsignal

crates/ruff_server/README.md

@@ -9,8 +9,33 @@ 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.
-- Neovim: See the [Neovim setup guide](docs/setup/NEOVIM.md).
+#### 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:
+
+![A screenshot showing an enabled "Native Server" extension setting in the VS Code settings view](assets/nativeServer.png)
+
+You can also set it in your user / workspace JSON settings as follows:
+
+```json
+{
+    "ruff.nativeServer": true
+}
+```
+
+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
 

crates/ruff_server/assets/nativeServer.png

@@ -0,0 +1,82 @@
+## 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 `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=<RULES>`
+to `lint.args`, you can migrate to the new server by using `lint.select` with a value of `["<RULES>"]`.
+
+### Examples
+
+Let's say you have these settings in VS Code:
+
+```json
+{
+    "ruff.lint.args": "--select=E,F --line-length 80 --config ~/.config/custom_ruff_config.toml"
+}
+```
+
+These can be migrated to the new language server like so:
+
+```json
+{
+    "ruff.configuration": "~/.config/custom_ruff_config.toml",
+    "ruff.lineLength": 80,
+    "ruff.lint.select": ["E", "F"]
+}
+```
+
+Similarly, let's say you have these settings in Helix:
+
+```toml
+[language-server.ruff.config.lint]
+args = "--select=E,F --line-length 80 --config ~/.config/custom_ruff_config.toml"
+```
+
+These can be migrated like so:
+
+```toml
+[language-server.ruff.config]
+configuration = "~/.config/custom_ruff_config.toml"
+lineLength = 80
+
+[language-server.ruff.config.lint]
+select = ["E", "F"]
+```

crates/ruff_server/docs/MIGRATION.md

@@ -34,7 +34,7 @@ language-servers = ["ruff", "pylsp"]
 
 Once you've set up the server, you should see diagnostics in your Python files. Code actions and other LSP features should also be available.
 
-![image](assets/SuccessfulHelixSetup.png "A screenshot showing an open Python file in Helix with highlighted diagnostics and a code action dropdown menu open")
+![A screenshot showing an open Python file in Helix with highlighted diagnostics and a code action dropdown menu open](assets/SuccessfulHelixSetup.png)
 *This screenshot is using `select=["ALL]"` for demonstration purposes.*
 
 If you want to, as an example, turn on auto-formatting, add `auto-format = true`: