From cc3a61e1ea40e860d01171c2585e5b3794fa587c Mon Sep 17 00:00:00 2001 From: Ronny Pfannschmidt Date: Tue, 29 Jul 2025 21:55:40 +0200 Subject: [PATCH 1/4] fix #1100: document readthedocs workaround for dirty worktrees --- CHANGELOG.md | 1 + docs/integrations.md | 26 ++++++++++++++++++++++++++ mkdocs.yml | 1 + 3 files changed, 28 insertions(+) create mode 100644 docs/integrations.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 72e655de..f5360893 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -33,6 +33,7 @@ - add support for failing on missing submodules - fix #279: expand errors when scm can be found upwards and relative_to wasnt used - fix #577: introduce explicit scmversion node and short node +- fix #1100: add workaround for readthedocs worktress to the docs ## v8.3.1 diff --git a/docs/integrations.md b/docs/integrations.md new file mode 100644 index 00000000..09828b04 --- /dev/null +++ b/docs/integrations.md @@ -0,0 +1,26 @@ +# Integrations + +## ReadTheDocs + +### Avoid having a dirty Git index + +When building documentation on ReadTheDocs, file changes during the build process can cause setuptools-scm to detect a "dirty" working directory. + +To avoid this issue, ReadTheDocs recommends using build customization to clean the Git state after checkout: + +```yaml title=".readthedocs.yaml" +version: 2 +build: + os: "ubuntu-22.04" + tools: + python: "3.10" + jobs: + post_checkout: + # Avoid setuptools-scm dirty Git index issues + - git reset --hard HEAD + - git clean -fdx +``` + +This ensures a clean Git working directory before setuptools-scm detects the version, preventing unwanted local version components. + +Reference: [ReadTheDocs Build Customization - Avoid having a dirty Git index](https://docs.readthedocs.com/platform/stable/build-customization.html#avoid-having-a-dirty-git-index) \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 7d0553f8..5b1f42ef 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -5,6 +5,7 @@ nav: - usage.md - customizing.md - config.md + - integrations.md - extending.md - overrides.md - changelog.md From 8d58d62f7207aaee3bb6eab6b60565be5f7ba19c Mon Sep 17 00:00:00 2001 From: Ronny Pfannschmidt Date: Tue, 29 Jul 2025 22:03:41 +0200 Subject: [PATCH 2/4] fix #790: document rtd workaround to ensure failure on too shallow scm --- CHANGELOG.md | 1 + docs/integrations.md | 26 +++++++++++++++++++++++++- 2 files changed, 26 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f5360893..9c5207c9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -34,6 +34,7 @@ - fix #279: expand errors when scm can be found upwards and relative_to wasnt used - fix #577: introduce explicit scmversion node and short node - fix #1100: add workaround for readthedocs worktress to the docs +- fix #790: document shallow fail for rtd ## v8.3.1 diff --git a/docs/integrations.md b/docs/integrations.md index 09828b04..ba097fe6 100644 --- a/docs/integrations.md +++ b/docs/integrations.md @@ -23,4 +23,28 @@ build: This ensures a clean Git working directory before setuptools-scm detects the version, preventing unwanted local version components. -Reference: [ReadTheDocs Build Customization - Avoid having a dirty Git index](https://docs.readthedocs.com/platform/stable/build-customization.html#avoid-having-a-dirty-git-index) \ No newline at end of file + + +Reference: [ReadTheDocs Build Customization - Avoid having a dirty Git index](https://docs.readthedocs.com/platform/stable/build-customization.html#avoid-having-a-dirty-git-index) + + +### Enforce fail on shallow repositories + +ReadTheDocs may sometimes use shallow Git clones that lack the full history needed for proper version detection. You can use setuptools-scm's environment variable override system to enforce `fail_on_shallow` when building on ReadTheDocs: + +```yaml title=".readthedocs.yaml" +version: 2 +build: + os: "ubuntu-22.04" + tools: + python: "3.10" + jobs: + post_checkout: + # Avoid setuptools-scm dirty Git index issues + - git reset --hard HEAD + - git clean -fdx + # Enforce fail_on_shallow for setuptools-scm + - export SETUPTOOLS_SCM_OVERRIDES_FOR_${READTHEDOCS_PROJECT//-/_}='{scm.git.pre_parse="fail_on_shallow"}' +``` + +This configuration uses the `SETUPTOOLS_SCM_OVERRIDES_FOR_${NORMALIZED_DIST_NAME}` environment variable to override the `scm.git.pre_parse` setting specifically for your project when building on ReadTheDocs, forcing setuptools-scm to fail with a clear error if the repository is shallow. \ No newline at end of file From befbdaa47f14a7f57a389f07e30c8df36aa996a5 Mon Sep 17 00:00:00 2001 From: Ronny Pfannschmidt Date: Wed, 30 Jul 2025 09:32:52 +0200 Subject: [PATCH 3/4] make griffe only report as warning --- .github/workflows/api-check.yml | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/.github/workflows/api-check.yml b/.github/workflows/api-check.yml index 97f500dd..18b7d4ed 100644 --- a/.github/workflows/api-check.yml +++ b/.github/workflows/api-check.yml @@ -34,5 +34,20 @@ jobs: pip install -e .[test] - name: Run griffe API check + id: griffe-check run: | - griffe check setuptools_scm -ssrc -f github \ No newline at end of file + if griffe check setuptools_scm -ssrc -f github; then + echo "api_check_result=success" >> $GITHUB_OUTPUT + else + echo "api_check_result=warning" >> $GITHUB_OUTPUT + echo "API stability check detected changes but will not fail the build" >> $GITHUB_STEP_SUMMARY + fi + + - name: Report API check result + if: steps.griffe-check.outputs.api_check_result == 'warning' + uses: actions/github-script@v7 + with: + script: | + core.warning('API stability check detected breaking changes. Please review the API changes above.') + core.summary.addRaw('⚠️ API Stability Warning: Breaking changes detected in the public API') + await core.summary.write() \ No newline at end of file From 6655627c43fb1a49d3fa425666a80d3899fdcf76 Mon Sep 17 00:00:00 2001 From: Ronny Pfannschmidt Date: Wed, 30 Jul 2025 09:50:05 +0200 Subject: [PATCH 4/4] fix #474: mention the pretend version vars on the error --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9c5207c9..70515bb8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -35,6 +35,7 @@ - fix #577: introduce explicit scmversion node and short node - fix #1100: add workaround for readthedocs worktress to the docs - fix #790: document shallow fail for rtd +- fix #474: expand version not found error message to provide clearer guidance about SETUPTOOLS_SCM_PRETEND_VERSION_FOR_* environment variables ## v8.3.1