Clarify documentation and correct stale guidance

CONTRIBUTING.md

@@ -434,7 +434,7 @@ screenshots or recordings of your change in action.
 After opening the PR, an ecosystem report will be run as part of CI. This shows
 a diff of linter and formatter behavior before and after the changes in your PR.
 Going through these changes and reporting your findings in the PR summary or an
-additional comment help us to review your PR more efficiently. It's also a great
+additional comment helps us review your PR more efficiently. It's also a great
 way to find new test cases to incorporate into your PR if you identify any
 issues.
 
@@ -472,12 +472,11 @@ The documentation should then be available locally at
 
 ## Release Process
 
-As of now, Ruff has an ad hoc release process: releases are cut with high frequency via GitHub
+As of now, Ruff has an ad hoc release process: releases are cut frequently via GitHub
 Actions, which automatically generates the appropriate wheels across architectures and publishes
 them to [PyPI](https://pypi.org/project/ruff/).
 
-Ruff follows the [semver](https://semver.org/) versioning standard. However, as pre-1.0 software,
-even patch releases may contain [non-backwards-compatible changes](https://semver.org/#spec-item-4).
+See Ruff's [versioning policy](https://docs.astral.sh/ruff/versioning/).
 
 ### Installing tools
 
@@ -506,7 +505,7 @@ review and remaining preparation steps below. To prepare the release locally, st
 
 1. The changelog should then be editorialized for consistency
 
-    - Often labels will be missing from pull requests they will need to be manually organized into the proper section
+    - Pull requests often lack labels and will need to be manually organized into the proper section
     - Changes should be edited to be user-facing descriptions, avoiding internal details
     - Square brackets (eg, `[ruff]` project name) will be automatically escaped by `prek`
 
@@ -1110,8 +1109,8 @@ The project root does not have a significant impact beyond that all relative pat
 configuration file are resolved relative to the project root.
 
 For example, to indicate that `bar` above is a namespace package (it isn't, but let's run with it),
-the `pyproject.toml` would list `namespace-packages = ["./src/bar"]`, which would resolve
-to `my_project/src/bar`.
+the `pyproject.toml` would list `namespace-packages = ["./src/foo/bar"]`, which would resolve
+to `my_project/src/foo/bar`.
 
 The same logic applies when providing a configuration file via `--config`. In that case, the
 _current working directory_ is used as the project root, and so all paths in that configuration file
@@ -1180,5 +1179,5 @@ There are three ways in which an import can be categorized as "first-party":
     the `src` setting and, for each directory, check for the existence of a subdirectory `foo` or a
     file `foo.py`.
 
-By default, `src` is set to the project root, along with `"src"` subdirectory in the project root.
+By default, `src` is set to the project root, along with the `"src"` subdirectory in the project root.
 This ensures that Ruff supports both flat and "src" layouts out of the box.

README.md

@@ -46,7 +46,7 @@ Ruff can be used to replace [Flake8](https://pypi.org/project/flake8/) (plus doz
 [autoflake](https://pypi.org/project/autoflake/), and more, all while executing tens or hundreds of
 times faster than any individual tool.
 
-Ruff is extremely actively developed and used in major open-source projects like:
+Ruff is actively developed and used in major open-source projects like:
 
 - [Apache Airflow](https://github.com/apache/airflow)
 - [Apache Superset](https://github.com/apache/superset)
@@ -381,7 +381,7 @@ quality tools, including:
 - [tryceratops](https://pypi.org/project/tryceratops/)
 - [yesqa](https://pypi.org/project/yesqa/)
 
-For a complete enumeration of the supported rules, see [_Rules_](https://docs.astral.sh/ruff/rules/).
+For the complete list of supported rules, see [_Rules_](https://docs.astral.sh/ruff/rules/).
 
 ## Contributing<a id="contributing"></a>
 

docs/configuration.md

@@ -251,10 +251,9 @@ For a complete enumeration of the available configuration options, see [_Setting
 ## Config file discovery
 
 Similar to [ESLint](https://eslint.org/docs/latest/use/configure/configuration-files#cascading-configuration-objects),
-Ruff supports hierarchical configuration, such that the "closest" config file in the
-directory hierarchy is used for every individual file, with all paths in the config file
-(e.g., `exclude` globs, `src` paths) being resolved relative to the directory containing that
-config file.
+Ruff supports hierarchical configuration. For each file, Ruff uses the "closest" config file in the
+directory hierarchy. Paths in that config file (e.g., `exclude` globs and `src` paths) are resolved
+relative to the directory containing it.
 
 There are a few exceptions to these rules:
 
@@ -264,9 +263,11 @@ There are a few exceptions to these rules:
     analyzed files, and any relative paths in that configuration file (like `exclude` globs or
     `src` paths) are resolved relative to the _current_ working directory.
 1. If no config file is found in the filesystem hierarchy, Ruff will fall back to using
-    a default configuration. If a user-specific configuration file exists
-    at `${config_dir}/ruff/pyproject.toml`, that file will be used instead of the default
-    configuration, with `${config_dir}` being determined via [`etcetera`'s base strategy](https://docs.rs/etcetera/latest/etcetera/#native-strategy),
+    a default configuration. If a user-specific configuration file exists at
+    `${config_dir}/ruff/.ruff.toml`, `${config_dir}/ruff/ruff.toml`, or
+    `${config_dir}/ruff/pyproject.toml` (checked in that order), the first such file will be used
+    instead of the default configuration, with `${config_dir}` being determined via
+    [`etcetera`'s base strategy](https://docs.rs/etcetera/latest/etcetera/#native-strategy),
     and all relative paths being again resolved relative to the _current working directory_.
 1. Any config-file-supported settings that are provided on the command-line (e.g., via
     `--select`) will override the settings in _every_ resolved configuration file.
@@ -347,7 +348,8 @@ For example, without `force-exclude` enabled, `ruff check /path/to/excluded/file
 
 ### Default inclusions
 
-By default, Ruff will discover files matching `*.py`, `*.pyi`, `*.ipynb`, or `pyproject.toml`.
+By default, Ruff will discover files matching `*.py`, `*.pyi`, `*.ipynb`, `*.md`, `pyproject.toml`,
+`ruff.toml`, or `.ruff.toml`.
 In [preview](preview.md) mode, Ruff will also discover `*.pyw` by default.
 
 To lint or format files with additional file extensions, use the [`extend-include`](settings.md#extend-include) setting.
@@ -446,7 +448,7 @@ using the [`per-file-ignores`](settings.md#per-file-ignores) setting:
 Some rules have different behavior when applied to Jupyter Notebook files. For
 example, when applied to `.py` files the
 [`module-import-not-at-top-of-file` (`E402`)](rules/module-import-not-at-top-of-file.md)
-rule detect imports at the top of a file, but for notebooks it detects imports at the top of a
+rule detects imports that are not at the top of a file. In notebooks, it applies that check to each
 **cell**. For a given rule, the rule's documentation will always specify if it has different
 behavior when applied to Jupyter Notebook files.
 
@@ -520,7 +522,7 @@ Ruff supports reading command-line arguments from a file, which is especially us
 $ ruff check @path/to/args.txt
 ```
 
-The arguments in the file must all be written on their own line. For example, `args.txt` might contain:
+Each argument in the file must be written on its own line. For example, `args.txt` might contain:
 
 ```text
 --select

docs/editors/features.md

@@ -4,7 +4,7 @@ This section provides a detailed overview of the features provided by the Ruff L
 
 ## Diagnostic Highlighting
 
-Provide diagnostics for your Python code in real-time.
+The server provides diagnostics for your Python code in real time.
 
 <img
 src="https://astral.sh/static/GIF/v0.4.5/violation_hx.gif"
@@ -27,8 +27,7 @@ alt="Editing a `pyproject.toml` configuration file in VS Code"
 
 ## Formatting
 
-Provide code formatting for your Python code. The server can format an entire document or a specific
-range of lines.
+The server can format an entire Python document or a specific range of lines.
 
 The VS Code extension provides the `Ruff: Format Document` command to format an entire document.
 In VS Code, the range formatting can be triggered by selecting a range of lines, right-clicking, and
@@ -120,8 +119,8 @@ how fix safety works.
 
 ## Hover
 
-The server can provide the rule documentation when focusing over a NoQA code in the comment.
-Focusing is usually hovering with a mouse, but can also be triggered with a shortcut.
+The server can provide rule documentation when you focus on a NoQA code in a comment. You can
+usually do this by hovering with a mouse or using a keyboard shortcut.
 
 <img
 src="https://astral.sh/static/GIF/v0.4.5/hover_vscode.gif"

docs/editors/index.md

@@ -13,10 +13,9 @@ backend built directly into Ruff, and a direct replacement for [`ruff-lsp`](http
 our previous language server. You can read more about `ruff server` in the
 [`v0.4.5` blog post](https://astral.sh/blog/ruff-v0.4.5).
 
-The server supports surfacing Ruff diagnostics, providing Code Actions to fix them, and
-formatting the code using Ruff's built-in formatter. Currently, the server is intended to be used
-alongside another Python Language Server in order to support features like navigation and
-autocompletion.
+The server provides Ruff diagnostics, Code Actions to fix them, and formatting using Ruff's built-in
+formatter. For features like navigation and autocompletion, we recommend using the
+[ty language server](https://docs.astral.sh/ty/features/language-server/) alongside Ruff.
 
 The Ruff Language Server was available first in Ruff [v0.4.5](https://astral.sh/blog/ruff-v0.4.5)
 in beta and stabilized in Ruff [v0.5.3](https://github.com/astral-sh/ruff/releases/tag/0.5.3).

docs/editors/migration.md

@@ -1,10 +1,9 @@
 # Migrating from `ruff-lsp`
 
-[`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.
+Ruff's previous [Language Server Protocol] implementation, [`ruff-lsp`][ruff-lsp], was written in
+Python and distributed separately from Ruff. It is no longer supported. This guide explains how to
+migrate to Ruff's **native server**, which is written in Rust and available through the
+`ruff server` command.
 
 !!! note
 
@@ -76,8 +75,8 @@ If you've been providing a configuration file as shown below:
 }
 ```
 
-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:
+To migrate to the new server, use the [`configuration`](settings.md#configuration) setting to apply
+the configuration to both the linter and the formatter:
 
 ```json
 {

docs/editors/settings.md

@@ -1,11 +1,9 @@
 # Settings
 
-The Ruff Language Server provides a set of configuration options to customize its behavior
-along with the ability to use an existing `pyproject.toml` or `ruff.toml` file to configure the
-linter and formatter. This is done by providing these settings while initializing the server.
-VS Code provides a UI to configure these settings, while other editors may require manual
-configuration. The [setup](./setup.md) section provides instructions on where to place these settings
-as per the editor.
+The Ruff Language Server accepts settings to customize its behavior and can use an existing
+`pyproject.toml` or `ruff.toml` file to configure the linter and formatter. Provide these settings
+when initializing the server. VS Code provides a UI for them, while other editors may require manual
+configuration. The [setup](./setup.md) section explains where to place the settings for each editor.
 
 ## Top-level
 
@@ -31,8 +29,8 @@ editor-provided configuration (`configuration`) and a project level configuratio
 
 #### Resolution order {: #configuration_resolution_order }
 
-In an editor, Ruff supports three sources of configuration, prioritized as follows (from highest to
-lowest):
+With the default `"editorFirst"` configuration preference, Ruff prioritizes the three sources of
+configuration as follows (from highest to lowest):
 
 1. **Specific settings:** Individual settings like [`lineLength`](#linelength) or
     [`lint.select`](#select) defined in the editor
@@ -47,7 +45,7 @@ For example, if the line length is specified in all three sources, Ruff will use
 
 **Default value**: `null`
 
-**Type**: `string`
+**Type**: `string` (path to a configuration file) or `object` (inline configuration)
 
 **Example usage**:
 
@@ -102,7 +100,7 @@ _Using inline configuration:_
                 "flake8-tidy-imports": {
                     "banned-api": {
                         "typing.TypedDict": {
-                            "msg": "Use `typing_extensions.TypedDict` instead",
+                            "msg": "Use `typing_extensions.TypedDict` instead"
                         }
                     }
                 }
@@ -178,7 +176,7 @@ The strategy to use when resolving settings across VS Code and the filesystem. B
 configuration is prioritized over `ruff.toml` and `pyproject.toml` files.
 
 - `"editorFirst"`: Editor settings take priority over configuration files present in the workspace.
-- `"filesystemFirst"`: Configuration files present in the workspace takes priority over editor
+- `"filesystemFirst"`: Configuration files present in the workspace take priority over editor
     settings.
 - `"editorOnly"`: Ignore configuration files entirely i.e., only use editor settings.
 
@@ -249,7 +247,7 @@ documentation](https://docs.astral.sh/ruff/settings/#exclude) for more details.
     vim.lsp.config('ruff', {
       init_options = {
         settings = {
-          exclude = ["**/tests/**"]
+          exclude = { "**/tests/**" }
         }
       }
     })
@@ -973,7 +971,7 @@ Whether to enable Ruff's preview mode when formatting.
 
 ### `backend` {: #format_backend }
 
-The backend to use for formatting files. Following options are available:
+The backend to use for formatting files. The following options are available:
 
 - `"internal"`: Use the built-in Ruff formatter
 - `"uv"`: Use uv for formatting (requires uv >= 0.8.13)
@@ -1114,9 +1112,9 @@ automatically decide between the two based on the Ruff version and extension set
 
 ### `path`
 
-A list of path to `ruff` executables.
+A list of paths to `ruff` executables.
 
-The first executable in the list which is exists is used. This setting takes precedence over the
+The first executable in the list that exists is used. This setting takes precedence over the
 [`ruff.importStrategy`](#importstrategy) setting.
 
 **Default value**: `[]`

docs/editors/setup.md

@@ -10,7 +10,7 @@ the [migration guide](./migration.md) for more.
 !!! note
 
     The setup instructions provided below are on a best-effort basis. If you encounter any issues
-    while setting up the Ruff in an editor, please [open an issue](https://github.com/astral-sh/ruff/issues/new)
+    while setting up Ruff in an editor, please [open an issue](https://github.com/astral-sh/ruff/issues/new)
     for assistance and help in improving this documentation.
 
 ## VS Code
@@ -25,11 +25,11 @@ For more documentation on the Ruff extension, refer to the
 
 ## Neovim
 
-The Ruff language server can be setup in Neovim using the built-in LSP client either via
+The Ruff language server can be set up in Neovim using the built-in LSP client either via
 [`vim.lsp.config`](<https://neovim.io/doc/user/lsp.html#vim.lsp.config()>) (Neovim 0.11+) or the
 [`nvim-lspconfig`](https://github.com/neovim/nvim-lspconfig) plugin (Neovim 0.10 and earlier).
 
-To setup using [`vim.lsp.config`](<https://neovim.io/doc/user/lsp.html#vim.lsp.config()>), you can
+To set up using [`vim.lsp.config`](<https://neovim.io/doc/user/lsp.html#vim.lsp.config()>), you can
 either use the [default configuration provided in
 `nvim-lspconfig`](https://github.com/neovim/nvim-lspconfig/blob/master/lsp/ruff.lua) or configure
 the server without any external dependencies.
@@ -433,7 +433,7 @@ IntelliJ Marketplace (maintained by [@koxudaxi](https://github.com/koxudaxi)).
 
 ## Emacs
 
-Ruff can be utilized as a language server via [`Eglot`](https://github.com/joaotavora/eglot), which is in Emacs's core.
+Ruff can be used as a language server via [`Eglot`](https://github.com/joaotavora/eglot), which is in Emacs's core.
 To enable Ruff with automatic formatting on save, use the following configuration:
 
 ```elisp