docs: add a section on when to use extends vs cascading (#20268)

Tanujkanti4441 · web-flow · commit 51b51f4f1ce8 · 2025-11-03T21:57:24.000+01:00
* docs: add section when to use extends vs cascading

* apply suggestions

* fix lint error

* remove space
diff --git a/docs/src/use/configure/configuration-files.md b/docs/src/use/configure/configuration-files.md
@@ -706,6 +706,27 @@ In this example, `exampleConfig` can be either an object or an array, and either
 
 For more information on how to combine shareable configs with your preferences, please see [Combine Configs](combine-configs).
 
+### When to Use Extends vs Cascading
+
+When to use `Extends`:
+
+- **For reusing configurations** - When you want to inherit and build upon existing configurations from plugins, shareable packages, or predefined configs.
+- **For plugin configuration** - When applying recommended or specific configurations from ESLint plugins (e.g., `example/recommended`).
+- **For shareable configurations** - When using npm packages that export configuration objects (e.g., `eslint-config-example`).
+- **For predefined configurations** - When using ESLint's built-in configurations like `js/recommended` or `js/all`.
+- **For modular configuration** - When you want to compose multiple configuration sources into a single configuration object.
+- **For maintaining consistency** - When you want to ensure consistent base rules across multiple configuration objects.
+- **For plugin integration** - When you need to apply configurations that come bundled with plugins.
+
+When to use `Cascading`:
+
+- **For file-specific rule** - When you need different rules for different file patterns or directories.
+- **For progressive configuration** - When you want to apply base rules to all files and then add/override rules for specific subsets.
+- **For environment-specific settings** - When test files, source files, and config files need different rule sets.
+- **For directory-based configuration** - When different project directories require different linting approaches.
+- **For rule severity adjustment** - When you want to change rule severity (`error`/`warn`/`off`) for specific file patterns.
+- **For language option variations** - When different files need different ECMAScript versions or parser options.
+
 ### Configuration Naming Conventions
 
 The `name` property is optional, but it is recommended to provide a name for each configuration object, especially when you are creating shared configurations. The name is used in error messages and the config inspector to help identify which configuration object is being used.
