search

readthedocs / readthedocs.org

The source code that powers readthedocs.org
https://readthedocs.org/
MIT License
8.03k stars 3.58k forks source link

Build: `READTHEDOCS_GIT_IDENTIFIER` shouldn't be the commit SHA on versions from tags #11662

Open drewcassidy opened 2 weeks ago

drewcassidy commented 2 weeks ago

Details

I'm using READTHEDOCS_GIT_IDENTIFIER in my docs to indicate the git tag to check out for a GitHub action. Unfortunately its rendering as the raw SHA

Expected Result

READTHEDOCS_GIT_IDENTIFIER is the name of the tag that was checked out

this is what the docs say it should be

Actual Result

READTHEDOCS_GIT_IDENTIFIER is the raw commit SHA

Workaround

I guess I can do a git describe

humitos commented 2 weeks ago

What's the URL of your project? What's the URL of the build where you're noticing this?

drewcassidy commented 2 weeks ago

What's the URL of your project? What's the URL of the build where you're noticing this?

Added. I pasted the URLs into the template wrong I guess

humitos commented 2 weeks ago

READTHEDOCS_GIT_IDENTIFIER is the raw commit SHA

Where I should check the content of this variable in your documentation? I'm not able to find the the SHA in the page you linked.

drewcassidy commented 2 weeks ago

the example line of - uses: KSPModdingLibs/KSPBuildTools/.github/actions/assemble-release@f89bab355278f61eabb8d8848746a9ce74a256bd is auto-generated using that environment variable

It should say - uses: KSPModdingLibs/KSPBuildTools/.github/actions/assemble-release@0.0.2-alpha.7 since the tag name being built is 0.0.2-alpha.7

humitos commented 2 weeks ago

I'm not able to reproduce this issue. I did a try at https://test-builds.readthedocs.io/en/full-feature/environment-variables.html and you can see there that READTHEDOCS_GIT_COMMIT_HASH: 185f27fa0b5d052862be2fca53c19ddb22d325e6 and READTHEDOCS_GIT_IDENTIFIER: full-feature. Those variables are pointing to the correct values.

humitos commented 2 weeks ago

I think that variable is never the tag name. It seems that it can only be a branch name and or a commit sha when it's a tag. Using my previous branch, I created a tag named v0.1-full-feature and built it on Read the Docs.

Taking a look at the same page, https://test-builds.readthedocs.io/en/v0.1-full-feature/environment-variables.html, we can see that both environment variables have the same value and it's a commit sha.

We use Version.identifier for READTHEDOCS_GIT_IDENTIFIER and based on what this comment says, it will always be a SHA if it's a tag: https://github.com/readthedocs/readthedocs.org/blob/173d0448bbad1b5953978ffad300890d366eb57c/readthedocs/builds/models.py#L107-L114

I found that calling git describe as you mentioned you can get the tag's name from a commit:

▶ git describe --tags 185f27fa0b5d052862be2fca53c19ddb22d325e6
v0.1-full-feature

This is a bug and we should fix it.