chore(docs): mention conflicting tools in upgrades (#7324)

ferrarimarco · web-flow · commit 7afe608fff92 · 2025-12-23T15:24:14.000+01:00
Close #7298
diff --git a/docs/add-new-linter.md b/docs/add-new-linter.md
@@ -214,6 +214,9 @@ documentation of the new tool.
    the user if the tools that might conflict with each other are enabled at the
    same time.
 
+1. Update the [upgrade guide](./upgrade-guide.md) to mention the addition of a
+   potentially conflicting linter.
+
 ### Configure the new tool for the Super-linter repository
 
 If the default configuration of the new tool is unsuitable for the Super-linter
diff --git a/docs/upgrade-guide.md b/docs/upgrade-guide.md
@@ -11,11 +11,34 @@ This document helps you upgrade from a super-linter version to newer ones:
 
 ## Upgrade from v8.1.0 to v8.2.0
 
+This section helps you upgrade from super-linter `v8.1.0` to `v8.2.0`.
+
+### Kubeconform
+
 Super-linter `v8.2.0` adds back Kubeconform and related configuration variables:
 
 - `KUBERNETES_KUBECONFORM_OPTIONS`
 - `VALIDATE_KUBERNETES_KUBECONFORM`
 
+### Potentially conflicting linters and formatters
+
+Super-linter `v8.2.0` adds support for running:
+
+- Ruff as a formatter on Python files. This might conflict with Black
+  (Languages: `PYTHON_BLACK`).
+- Biome as a linter. This might conflict with stylelint (`CSS`), ESLint
+  (Languages: `JAVASCRIPT_ES`, `JSON`, `JSONC`, `JSX`, `TSX`, `TYPESCRIPT_ES`,
+  `VUE`)
+- Biome as a formatter. This might conflict with Prettier (Languages:
+  `CSS_PRETTIER`, `GRAPHQL_PRETTIER`, `HTML_PRETTIER`, `JAVASCRIPT_PRETTIER`,
+  `JSON_PRETTIER`, `JSONC_PRETTIER`, `JSX_PRETTIER`, `TYPESCRIPT_PRETTIER`,
+  `VUE_PRETTIER`).
+
+If you have potentially conflicting linters or formatters enabled, Super-linter
+will emit a warning message. To turn the conflicting tools warning into a
+failure that makes Super-linter exit with an error, set the
+`FAIL_ON_CONFLICTING_TOOLS_ENABLED` configuration variable to `true`.
+
 ## Upgrade from v7.4.0 to v8
 
 This section helps you upgrade from super-linter `v7.4.0` to `v8.0.0`.
