Stable build does not make git tag available during build

[djhoese]

Details

• Read the Docs project URL: https://readthedocs.org/projects/satpy/
• Build URL (if applicable): https://readthedocs.org/projects/satpy/builds/21839497/
• Read the Docs username (if applicable): https://readthedocs.org/profiles/davidh-ssec/

Expected Result

The "stable" build of my project is accurately grabbing the commit SHA associated with the most recent tag. I expect that during the build process there is enough git context for git commands to determine the name of the tag that is currently checked out. This is used heavily by dynamic version software (ex. setuptools-scm, versioneer, etc).

Actual Result

During the git checkout process of getting the repository it does not actually have any of the tag information. So when my python package calls into setuptools-scm to determine the version number it uses a fallback (nonsense) version number.

CC @gerritholl who identified the issue in our documentation.

If I run the same git commands as in the linked build above locally and then run setuptools-scm manually I get:

$ python -m setuptools_scm
/home/davidh/miniconda3/envs/satpy_py311_2/lib/python3.11/site-packages/setuptools_scm/git.py:135: UserWarning: "/tmp/rtd_test" is shallow and may cause errors
  warnings.warn(f'"{wd.path}" is shallow and may cause errors')
0.1.dev10921+g18288df

If I instead checkout all commits (just as a test), then checkout the specific SHA, then run it I get:

$ python -m setuptools_scm
/home/davidh/miniconda3/envs/satpy_py311_2/lib/python3.11/site-packages/setuptools_scm/git.py:135: UserWarning: "/tmp/rtd_test" is shallow and may cause errors
  warnings.warn(f'"{wd.path}" is shallow and may cause errors')
0.43.0

Am I maybe breaking something with my .readthedocs.yaml?

[humitos]

I'm not sure if this solves exactly what you are reporting, but have you read https://docs.readthedocs.io/en/latest/build-customization.html#avoid-having-a-dirty-git-index?

[djhoese]

@humitos Good guess and that may be needed in the future as I notice that the version number in our actual stable build is different from produced locally. On the RTD build:

Satpy 0.1.dev1407+g18288df.d20230807 documentation

And after re-reading the setuptools-scm README we can see the different variations of the version number:

https://github.com/pypa/setuptools_scm/#default-versioning-scheme

The above version would be the "distance and not clean". So git/setuptools-scm seems to be finding a "0.1" tag somewhere and detecting that our current commit is 1407 ahead of that and then it has the date of that commit. But it doesn't have any regular git tag information otherwise. I'll triple check on the 0.1 git tag and see where that is coming from.

Any other guesses? Has anything changed in the last ~6 months with how RTD gets code with git?

[humitos]

Any other guesses? Has anything changed in the last ~6 months with how RTD gets code with git?

Actually, yes.

• Old build: https://beta.readthedocs.org/projects/satpy/builds/21186960/
• New build: https://beta.readthedocs.org/projects/satpy/builds/21839497/

Take a look at the Git commands, they a little different. Do you think this may be related to your case?

From those two different builds, I noticed that the build from 2 months ago uses the exact same commit than the build from an hour ago 🤷🏼

[djhoese]

That looks like it. Using that git clone command and the other git commands seems to work just fine for determining the package version.

Side note: I've created a pull request that follows the docs you linked to and it doesn't seem to solve the dirty git state.

[djhoese]

FYI I'm debugging why I was still getting a dirty git environment even after doing what the RTD docs suggest and it looks like I needed to add an explicit install of my package as a post_install job:

python -m pip install --no-deps -e .

which has the following output:

Obtaining file:///home/docs/checkouts/readthedocs.org/user_builds/satpy/checkouts/2567
  Installing build dependencies: started
  Installing build dependencies: finished with status 'done'
  Checking if build backend supports build_editable: started
  Checking if build backend supports build_editable: finished with status 'done'
  Getting requirements to build editable: started
  Getting requirements to build editable: finished with status 'done'
  Preparing editable metadata (pyproject.toml): started
  Preparing editable metadata (pyproject.toml): finished with status 'done'
Building wheels for collected packages: satpy
  Building editable for satpy (pyproject.toml): started
  Building editable for satpy (pyproject.toml): finished with status 'done'
  Created wheel for satpy: filename=satpy-0.43.1.dev122+g641a738c-0.editable-py2.py3-none-any.whl size=20367 sha256=98c5f2b7d9b0ca44011a8aedf8f502ee352d66f94011bbca99a2be88fcfa7b89
  Stored in directory: /tmp/pip-ephem-wheel-cache-_xe0lnjm/wheels/98/b8/ba/040917f2e26f23bc013cb85d20468f94638c1dc37071a7f04b
Successfully built satpy
Installing collected packages: satpy
  Attempting uninstall: satpy
    Found existing installation: satpy 0.43.1.dev122+g641a738c.d20230906
    Uninstalling satpy-0.43.1.dev122+g641a738c.d20230906:
      Successfully uninstalled satpy-0.43.1.dev122+g641a738c.d20230906
Successfully installed satpy-0.43.1.dev122+g641a738c

This shows it uninstalled a version of the package from a dirty environment (note the .d20230906 which is only in the dirty cases). I don't see a command in the build process that would have installed this version before my pre_install git update-index command.

[humitos]

From those two different builds, I noticed that the build from 2 months ago uses the exact same commit than the build from an hour ago 🤷🏼

@stsewd I think you had a similar issue some time ago and open a PR to fix this and ran a small migration code (I think it was this one: #10606). Do you think this could be related? Maybe we missed some of the affected projects?

[stsewd]

@humitos the commit looks correct https://github.com/pytroll/satpy/commits/v0.43.0

[djhoese]

Yes, the v0.43.0 version that I activated specifically due to this issue does succeed with a realistic version (dirty, but that's a different issue), but that's because it explicitly fetches the tags with:

 git fetch origin --force --prune --prune-tags --depth 50 refs/tags/v0.43.0:refs/tags/v0.43.0 

Whereas the stable build only pulls the single commit:

 git fetch origin --force --prune --prune-tags --depth 50 18288df8dc943fc07322f47c435c08113abb0b8a 

[humitos]

I'm confused now. It seems that stable points to the exact same commit than v0.43.0 and that looks correct to me. So, what's the problem we are trying to solve? 🤔

[AntoineD]

We are now facing the same issue for this doc.

As already noticed above, the git commands have changed and now the tags are absent which causes tools like setuptools-scm to no longer be able to determine the version.

It seems that the following git command

 git fetch origin --force --prune --prune-tags --depth 50 18288df8dc943fc07322f47c435c08113abb0b8a 

could be replaced by

 git fetch origin --force --prune --tags --depth 50 18288df8dc943fc07322f47c435c08113abb0b8a 

and the tags are back.

[humitos]

This is something that users can achieve with build.jobs.post_checkout to fetch the tags since it only affects projects using setuptools-scm.

[djhoese]

@humitos This does not only affect projects using setuptools-scm. It affects any project using git tags for versioning. Another example would be projects using versioneer or hatch-vcs. Anything that looks at the git tags won't find them.

And just because a tag and the "stable" version point to the same commit doesn't mean that RTD runs the same commands to get the git repository. It treats them as different things which I don't disagree with, but yeah git tags/history should almost always be checked out/fetched when getting a git repository.

[djhoese]

Here's a project of mine using versioneer with a public "stable" version of 1.27.1+0.g12892b8.dirty:

https://pyresample.readthedocs.io/en/stable/

So part of that is just the RTD change to modify the git repository (making it "dirty") which I'm still not sure I understand. Would RTD be open to a pull request to make RTD work without modifying the git repository?

[humitos]

git tags/history should almost always be checked out/fetched when getting a git repository.

I think this is what we want to avoid on the general use case because it penalizes all the projects by downloading more data than the one they need to build. I'd say that projects requiring tags/history to be available for usage should use build.jobs.post_checkout to fetch the data they need. It's pretty simple:

version: 2

build:
  jobs:
    post_checkout:
      - git fetch --tags

So part of that is just the RTD change to modify the git repository (making it "dirty") which I'm still not sure I understand.

This can be solved by https://docs.readthedocs.io/en/latest/build-customization.html#avoid-having-a-dirty-git-index

Would RTD be open to a pull request to make RTD work without modifying the git repository?

Yes, we are getting there and hopefully this will happen sooner than what we thought due to https://blog.readthedocs.com/addons-flyout-menu-beta/. We are working on a way to opt-in into this while keeping the same configuration and without requiring using build.commands.

[stsewd]

This is also kind of problem with stable storing just the commit instead of the tag name, this is because we store "stable" as the name instead of the tag (similar situation happens with latest...).

[stsewd]

This is also kind of problem with stable storing just the commit instead of the tag name, this is because we store "stable" as the name instead of the tag (similar situation happens with latest...).

In #10738 we fixed this situation in latest by tracking the name of the tag as the identifier, I think we can do the same for stable. But we should check if there are other parts of our code that depend on it being a commit (would be surprised if this was the case TBH).

[pllim]

I think I just hit a similar problem over at astropy: astropy/astropy#15954