update docs

Author: RonnyPfannschmidt

docs/config.md

@@ -2,11 +2,12 @@
 
 ## When is configuration needed?
 
-Starting with setuptools-scm 8.1+, explicit configuration is **optional** in many cases:
+Starting with setuptools-scm 9.0, explicit configuration is required to enable
+version inference, either via the `[tool.setuptools_scm]` section or the
+`use_scm_version` setup keyword. Listing `setuptools_scm` in `build-system.requires`
+and declaring `project.dynamic = ["version"]` no longer auto-enables inference.
 
-- **No configuration needed**: If `setuptools_scm` (or `setuptools-scm`) is in your `build-system.requires`, setuptools-scm will automatically activate with sensible defaults.
-
-- **Configuration recommended**: Use the `[tool.setuptools_scm]` section when you need to:
+Use the `[tool.setuptools_scm]` section when you need to:
   - Write version files (`version_file`)
   - Customize version schemes (`version_scheme`, `local_scheme`)
   - Set custom tag patterns (`tag_regex`)

docs/usage.md

@@ -7,30 +7,11 @@
     Support for setuptools <80 is deprecated and will be removed in a future release.
     The examples below use `setuptools>=80` as the recommended version.
 
-There are two ways to configure `setuptools-scm` at build time, depending on your needs:
+There are two ways to enable `setuptools-scm` at build time:
 
-### Automatic Configuration (Recommended for Simple Cases)
+### Explicit Configuration (required)
 
-For projects that don't need custom configuration, simply include `setuptools-scm`
-in your build requirements:
-
-```toml title="pyproject.toml"
-[build-system]
-requires = ["setuptools>=80", "setuptools-scm>=8"]
-build-backend = "setuptools.build_meta"
-
-[project]
-# version = "0.0.1"  # Remove any existing version parameter.
-dynamic = ["version"]
-```
-
-**That's it!** Starting with setuptools-scm 8.1+, if `setuptools_scm` (or `setuptools-scm`)
-is present in your `build-system.requires`, setuptools-scm will automatically activate
-with default settings.
-
-### Explicit Configuration
-
-If you need to customize setuptools-scm behavior, use the `tool.setuptools_scm` section:
+Add a `tool.setuptools_scm` section to explicitly opt-in to version inference:
 
 ```toml title="pyproject.toml"
 [build-system]
@@ -51,20 +32,28 @@ pre_parse = "fail_on_missing_submodules"  # Fail if submodules are not initializ
 describe_command = "git describe --dirty --tags --long --exclude *js*"  # Custom describe command
 ```
 
-Both approaches will work with projects that support PEP 518 ([pip](https://pypi.org/project/pip) and
-[pep517](https://pypi.org/project/pep517/)).
-Tools that still invoke `setup.py` must ensure build requirements are installed
+Projects must support PEP 518 ([pip](https://pypi.org/project/pip) and
+[pep517](https://pypi.org/project/pep517/)). Tools that still invoke `setup.py`
+must ensure build requirements are installed.
+
+### Using the setup keyword
+
+Alternatively, enable `setuptools-scm` via the `use_scm_version` keyword in `setup.py`.
+This also counts as an explicit opt-in and does not require a tool section.
 
-!!! info "How Automatic Detection Works"
+!!! warning "Simplified activation removed"
 
-    When setuptools-scm is listed in `build-system.requires`, it automatically detects this during the build process and activates with default settings. This means:
+    Previous documentation described a "simplified" activation where listing
+    `setuptools_scm` in `build-system.requires` together with `project.dynamic = ["version"]`
+    would auto-enable version inference. This behavior has been removed due to
+    regressions and ambiguous activation. You must explicitly opt in via either:
 
-    - ✅ **Automatic activation**: No `[tool.setuptools_scm]` section needed
-    - ✅ **Default behavior**: Uses standard version schemes and SCM detection
-    - ✅ **Error handling**: Provides helpful error messages if configuration is missing
-    - ⚙️ **Customization**: Add `[tool.setuptools_scm]` section when you need custom options
+    - a `[tool.setuptools_scm]` section, or
+    - the `use_scm_version` setup keyword.
 
-    Both package names are detected: `setuptools_scm` and `setuptools-scm` (with dash).
+    The presence of `setuptools_scm` (or `setuptools-scm`) in `build-system.requires`
+    is still recommended to ensure the dependency is available during builds, but it
+    no longer enables version inference by itself.
 
 ### Version files