more consistent documentation on setuptools version requirements and recommendations

closes #921

Author: RonnyPfannschmidt

CHANGELOG.md

@@ -28,6 +28,7 @@
 - fix #1150: enable setuptools-scm when we are a build requirement
 - feature #1154: add the commit id the the default version file template
 - drop scriv
+- fix #921: document setuptools version requirements more consistently - 61 as minumum asn 8 as recommended minimum
 
 ### Fixed
 

README.md

@@ -24,13 +24,13 @@ or [configuring Git archive][git-archive-docs].
 The preferred way to configure [setuptools-scm] is to author
 settings in a `tool.setuptools_scm` section of `pyproject.toml`.
 
-This feature requires setuptools 61 or later.
+This feature requires setuptools 61 or later (recommended: >=80 for best compatibility).
 First, ensure that [setuptools-scm] is present during the project's
 build step by specifying it as one of the build requirements.
 
 ```toml title="pyproject.toml"
 [build-system]
-requires = ["setuptools>=64", "setuptools-scm>=8"]
+requires = ["setuptools>=80", "setuptools-scm>=8"]
 build-backend = "setuptools.build_meta"
 ```
 
@@ -61,7 +61,7 @@ dynamic = ["version"]
 
     ```toml title="pyproject.toml"
     [build-system]
-    requires = ["setuptools>=64", "setuptools-scm>=8"]
+    requires = ["setuptools>=80", "setuptools-scm>=8"]
     build-backend = "setuptools.build_meta"
 
     [project]
@@ -108,6 +108,12 @@ modern [setuptools-scm] is unable to support them sensibly.
 It's strongly recommended to build a wheel artifact using modern Python and setuptools,
 then installing the artifact instead of trying to run against old setuptools versions.
 
+!!! note "Legacy Setuptools Support"
+    While setuptools-scm recommends setuptools >=80, it maintains compatibility with setuptools 61+
+    to support legacy deployments that cannot easily upgrade. Support for setuptools <80 is deprecated
+    and will be removed in a future release. This allows enterprise environments and older CI/CD systems
+    to continue using setuptools-scm while still encouraging adoption of newer versions.
+
 
 ## Code of Conduct
 

docs/customizing.md

@@ -33,7 +33,7 @@ setup(use_scm_version={"version_scheme": myversion_func})
 
 ``` { .toml title="pyproject.toml" file="docs/examples/version_scheme_code/pyproject.toml" }
 [build-system]
-requires = ["setuptools>=64", "setuptools-scm>=8"]
+requires = ["setuptools>=80", "setuptools-scm>=8"]  # setuptools>=61 minimum, >=80 recommended
 build-backend = "setuptools.build_meta"
 
 [project]

docs/examples/version_scheme_code/pyproject.toml

@@ -1,6 +1,6 @@
 # ~/~ begin <<docs/customizing.md#docs/examples/version_scheme_code/pyproject.toml>>[init]
 [build-system]
-requires = ["setuptools>=64", "setuptools-scm>=8"]
+requires = ["setuptools>=80", "setuptools-scm>=8"]  # setuptools>=61 minimum, >=80 recommended
 build-backend = "setuptools.build_meta"
 
 [project]

docs/index.md

@@ -27,12 +27,13 @@ or [configuring Git archive][git-archive-docs].
 ### With setuptools
 
 Note: `setuptools-scm>=8` intentionally doesn't depend on setuptools to ease non-setuptools usage.
-Please ensure a recent version of setuptools (>=64) is installed.
+Please ensure a recent version of setuptools is installed (minimum: >=61, recommended: >=80 for best compatibility).
+Support for setuptools <80 is deprecated and will be removed in a future release.
 
 
 ```toml title="pyproject.toml"
 [build-system]
-requires = ["setuptools>=64", "setuptools-scm>=8"]
+requires = ["setuptools>=80", "setuptools-scm>=8"]
 build-backend = "setuptools.build_meta"
 
 [project]

docs/usage.md

@@ -2,6 +2,11 @@
 
 ## At build time
 
+!!! note "Setuptools Version Requirements"
+    setuptools-scm requires setuptools 61 or later (minimum), but recommends >=80 for best compatibility.
+    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:
 
 ### Automatic Configuration (Recommended for Simple Cases)
@@ -11,7 +16,7 @@ in your build requirements:
 
 ```toml title="pyproject.toml"
 [build-system]
-requires = ["setuptools>=64", "setuptools-scm>=8"]
+requires = ["setuptools>=80", "setuptools-scm>=8"]
 build-backend = "setuptools.build_meta"
 
 [project]
@@ -29,7 +34,7 @@ If you need to customize setuptools-scm behavior, use the `tool.setuptools_scm`
 
 ```toml title="pyproject.toml"
 [build-system]
-requires = ["setuptools>=64", "setuptools-scm>=8"]
+requires = ["setuptools>=80", "setuptools-scm>=8"]
 build-backend = "setuptools.build_meta"
 
 [project]

src/setuptools_scm/_integration/setuptools.py

@@ -34,7 +34,7 @@ def _warn_on_old_setuptools(_version: str = setuptools.__version__) -> None:
 ERROR: setuptools=={_version} is used in combination with setuptools-scm>=8.x
 
 Your build configuration is incomplete and previously worked by accident!
-setuptools-scm requires setuptools>=61
+setuptools-scm requires setuptools>=61 (recommended: >=80)
 
 Suggested workaround if applicable:
  - migrating from the deprecated setup_requires mechanism to pep517/518