build warning: Git clone too shallow by bmunkholm · Pull Request #115 · crate/crate-docs

bmunkholm · 2025-06-23T18:38:49Z

testing latest build issue that occurs in all docs repos suddenly:

/home/docs/checkouts/readthedocs.org/user_builds/crate-docs/checkouts/115/docs/index.rst: WARNING: Git clone too shallow

The problem has been observed on those CI runs on GHA, and others: THEME-609, THEME-610.

bmunkholm · 2025-06-23T19:30:50Z

sphinx-last-updated-by-git is suddenly pulled in transitively due to a newer sphinx_sitemap (upgraded from 2.6.0 to 2.7.1) - c'est la vie when we don't use lock files for dependencies...

There are several ways to fix this as described in sphinx_last_updated_by_git.

Doing a full/partial fetch of the history when cloning instead of the shallow done by default.
Or disable the warning in conf.py with: suppress_warnings = ['git.too_shallow'].

@amotl Are aware to which extend it will have an effect to disable the warning? Or perhaps we should just do a fuller fetch to allow support for features instead of restricting them? It's still not clear for me what this new feature does (add last-updated date in sitemap.xml?) and if it actually has an effect on our site without other changes to support it?

Are we actually hosting a sitemap.xml file for our docs? (I could only see the root sitemap.xml file - is it included there?)

bmunkholm · 2025-06-23T20:45:10Z

Didn't check yet if we can do either of the solutions just in this repo or it's just makefile rules that are inherited from here to all the projects.

amotl · 2025-06-23T21:07:32Z

Hi. I don't know anything about relevant consequences, but any option can be explored. Another one, for example a quick one to restore the builds, would be to NOT upgrade to the offending sphinx_sitemap package, and continue a bit with the version that does not introduce any regressions. Then, we can probe other options without others waiting for unblocking the builds.

@msbt is the expert in maintaining our sitemap.xml's, but if you would like I can also gather relevant information. I dearly hope other departments didn't disconnect the documentation sitemap again, which happened in the past, not just once.

amotl · 2025-06-23T21:23:18Z

docs/conf.py

@@ -1 +1,3 @@
 from crate.theme.rtd.conf.theme import *
+
+#suppress_warnings = ['git.too_shallow']


This one will just apply to the documentation of this tool repository in isolation, nothing else. If we want to roll out a Sphinx setting across all documentation projects, crate-docs-theme is the right place.

I think suppressing warnings should only happen as a very last resort, of course always depending on circumstances.

Let's remove this, merge, and then spread it out to other repositories?

There are still a few open questions:

What depth is needed when fetching?

Do we get any value out of the new sphinx-sitemap? I.e. dates on when a page was updated? Is that for end users or search?

Can we disable this by configuration (assuming we don't need/want it). I remember seeing something, but don't recall exact config option right now...

Will this be fixed in sphinx-sitemap itself?

Therefore itt seems very attractive to be able to fix this temporarily for all docs builds just one place, so I would suggest to pin sphinx-sitemap in crate-docs-theme instead for now.

Hi Brian.

It seems very attractive to be able to fix this temporarily for all docs builds just one place, so I would suggest to crate/crate-docs-theme#611 instead for now.

That's absolutely way to go in such a situation, thank you so much.

amotl · 2025-06-23T21:30:29Z

.readthedocs.yml

+  jobs:
+    post_checkout:
+      - git fetch --unshallow || true


It looks like the build is not failing on RTD (is it?), so we don't need this update here, just for GHA?

No it also fails on RTD, so this is needed.

Oh ok. Do you have a sample? Maybe an update of Git on their ends responsible for the regression?

https://docs.readthedocs.com/platform/stable/build-customization.html#unshallow-git-clone describes this (in general). I doubt RTD can do anything about this except describe the issue in general?

https://app.readthedocs.org/projects/crate-jdbc/builds/28608809/ shows an example of the same build problem.

https://pypi.org/project/sphinx-last-updated-by-git/ describes how to handle this issue if the extension is used.

Wow, thanks.

amotl · 2025-06-23T21:30:50Z

Those tickets relay further information about the issue at hand.

Not working as expected for older projects using the PyData theme mgeier/sphinx-last-updated-by-git#54
Doesn't work on the production websites when using with GitHub pages mgeier/sphinx-last-updated-by-git#56

amotl · 2025-06-23T21:33:44Z

[...] gathering relevant information about documentation's sitemap.xml.

You can find more information on a non-public repository here.

test - ignore

e2905ff

bmunkholm changed the title ~~test - ignore~~ build warning: Git clone too shallow Jun 23, 2025

bmunkholm added 6 commits June 23, 2025 22:14

disable shallow warning

d7c8d03

fetch more

f3debcb

and enable the warning again

78ad02d

Update .readthedocs.yml config

2d4bd3e

Update .readthedocs.yml

fd45300

Update .readthedocs.yml

e2e7097

amotl reviewed Jun 23, 2025

View reviewed changes

amotl mentioned this pull request Jun 23, 2025

WARNING: Git clone too shallow jdillard/sphinx-sitemap#109

Open

amotl approved these changes Jun 24, 2025

View reviewed changes

bmunkholm mentioned this pull request Jun 24, 2025

pin sphinx-sitemap extension due to build warnings crate/crate-docs-theme#611

Merged

		@@ -1 +1,3 @@
		from crate.theme.rtd.conf.theme import *

		#suppress_warnings = ['git.too_shallow']

Conversation

bmunkholm commented Jun 23, 2025 • edited by amotl Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bmunkholm commented Jun 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bmunkholm commented Jun 23, 2025

Uh oh!

amotl commented Jun 23, 2025

Uh oh!

amotl Jun 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bmunkholm Jun 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

amotl Jun 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

amotl Jun 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

amotl commented Jun 23, 2025

Uh oh!

amotl commented Jun 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

bmunkholm commented Jun 23, 2025 •

edited by amotl

Loading

bmunkholm commented Jun 23, 2025 •

edited

Loading

amotl Jun 23, 2025 •

edited

Loading

bmunkholm Jun 24, 2025 •

edited

Loading

amotl Jun 25, 2025 •

edited

Loading

amotl Jun 23, 2025 •

edited

Loading

amotl commented Jun 23, 2025 •

edited

Loading