Improve documentation around linter-formatter conflicts (#8257)

Closes https://github.com/astral-sh/ruff/issues/8245.

docs/formatter.md

@@ -180,9 +180,10 @@ comments, which are treated equivalently to `# fmt: off` and `# fmt: on`, respec
 
 Ruff's formatter is designed to be used alongside the linter. However, the linter includes
 some rules that, when enabled, can cause conflicts with the formatter, leading to unexpected
-behavior.
+behavior. When configured appropriately, the goal of Ruff's formatter-linter compatibility is
+such that running the formatter should never introduce new lint errors.
 
-When using Ruff as a formatter, we recommend disabling the following rules:
+As such, when using Ruff as a formatter, we recommend avoiding the following lint rules:
 
 - [`tab-indentation`](rules/tab-indentation.md) (`W191`)
 - [`indentation-with-invalid-multiple`](rules/indentation-with-invalid-multiple.md) (`E111`)
@@ -199,7 +200,11 @@ When using Ruff as a formatter, we recommend disabling the following rules:
 - [`single-line-implicit-string-concatenation`](rules/single-line-implicit-string-concatenation.md) (`ISC001`)
 - [`multi-line-implicit-string-concatenation`](rules/multi-line-implicit-string-concatenation.md) (`ISC002`)
 
-Similarly, we recommend disabling the following isort settings, which are incompatible with the
+None of the above are included in Ruff's default configuration. However, if you've enabled
+any of these rules or their parent categories (like `Q`), we recommend disabling them via the
+linter's [`ignore`](settings.md#ignore) setting.
+
+Similarly, we recommend avoiding the following isort settings, which are incompatible with the
 formatter's treatment of import statements when set to non-default values:
 
 - [`force-single-line`](settings.md#isort-force-single-line)
@@ -208,6 +213,12 @@ formatter's treatment of import statements when set to non-default values:
 - [`lines-between-types`](settings.md#isort-lines-between-types)
 - [`split-on-trailing-comma`](settings.md#isort-split-on-trailing-comma)
 
+If you've configured any of these settings to take on non-default values, we recommend removing
+them from your Ruff configuration.
+
+When an incompatible lint rule or setting is enabled, `ruff format` will emit a warning. If your
+`ruff format` is free of warnings, you're good to go!
+
 ## Exit codes
 
 `ruff format` exits with the following status codes:

docs/integrations.md

@@ -55,6 +55,10 @@ or isort, _unless_ you enable autofix, in which case, Ruff's pre-commit hook sho
 Black, isort, and other formatting tools, as Ruff's autofix behavior can output code changes that
 require reformatting.
 
+As long as your Ruff configuration avoids any [linter-formatter incompatibilities](formatter.md#conflicting-lint-rules),
+`ruff format` should never introduce new lint errors, so it's safe to run Ruff's format hook _after_
+`ruff check --fix`.
+
 ## Language Server Protocol (Official)
 
 Ruff supports the [Language Server Protocol](https://microsoft.github.io/language-server-protocol/)