diff --git a/CHANGELOG.md b/CHANGELOG.md index 10d46481..c33f0ab4 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/README.md b/README.md index 7d9c056a..f4ca4bf9 100644 --- a/README.md +++ b/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 diff --git a/docs/customizing.md b/docs/customizing.md index 577da0cd..18ee8765 100644 --- a/docs/customizing.md +++ b/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] diff --git a/docs/examples/version_scheme_code/pyproject.toml b/docs/examples/version_scheme_code/pyproject.toml index 389aad09..a30582fe 100644 --- a/docs/examples/version_scheme_code/pyproject.toml +++ b/docs/examples/version_scheme_code/pyproject.toml @@ -1,6 +1,6 @@ # ~/~ begin <>[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] diff --git a/docs/index.md b/docs/index.md index b03291e3..303017f3 100644 --- a/docs/index.md +++ b/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] diff --git a/docs/usage.md b/docs/usage.md index 7938b4e6..9924ed49 100644 --- a/docs/usage.md +++ b/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] diff --git a/src/setuptools_scm/_integration/setuptools.py b/src/setuptools_scm/_integration/setuptools.py index 242f4152..e96807e4 100644 --- a/src/setuptools_scm/_integration/setuptools.py +++ b/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