Build fails for tagged versions

[JadeMatrix]

Details

• Read the Docs project URL: https://readthedocs.org/projects/show-cpp/
• Build URL: https://readthedocs.org/projects/show-cpp/builds/7145962/
• Read the Docs username: JadeMatrix

My most recent version release (0.8.4) failed to build on RTD but worked fine on my machine, so I did a little digging around. It appears RTD is trying to pull all versions as branches rather than tags:

I typically work off of version branches — for example named v0.8.3 — then delete the branch & release a version on GitHub with the same name, creating a tag with the same name as the old development branch. Looking at some of my older versions, I noticed that v0.8.3 built successfully during development, but the final build (based off the tag) failed. This made me think my issue was related to #3887. However RTD never picked up on my latest version v0.8.4 as a branch until I released it, and still failed as it was trying to clone a branch rather than the tag (screenshot & link above).

I tried wiping the version on RTD and rebuilding but it still fails. v0.8.2 and earlier all seemed to have built properly every time, but it doesn't look like a clone/checkout/pull was involved.

Release dates of the versions in question:

• v0.8.4 — May 5, 2018
• v0.8.3 — March 21, 2018
• v0.8.2 — January 30, 2018

Expected Result

RTD should run git checkout v0.8.4 and build the latest tag or branch that results in.

Actual Result

RTD builds the version branch properly (or sometimes not at all) during development, but fails to build the finalized version tag.

My latest is always correct, though, because that's building from the master branch. This leads to my current situation where latest shows the up-to-date documentation for my version v0.8.4, but the direct link to that version is a 404 because RTD never picked up on the branch during development.

[stsewd]

Have you seen if there is a version named 0.8.4_a (inactive maybe) under the versions section of your project?

[JadeMatrix]

Actually yes, there are inactive *_a versions for all three — must have missed them yesterday. Building 0.8.4_a works — should I be using these versions for pre-releases then?

[stsewd]

This is how rtd versions work: if you have a v0.8.3 branch and then you have a tag of the same name, rtd will create two versions 0.8.3 and 0.8.3_a. If you delete the branch/tag you just need to deactivate the version, then build the latest version to refresh the versions lists.

[JadeMatrix]

Okay, so I disabled 0.8.4_a, re-built latest, then under Admin → Versions enabled 0.8.4:

but it still shows up with a trailing _a unlike my other versions:

I see under Admin → Versions that 0.8.4 has a git hash associated with it; my other versions have two, one with a hash and one without. I've chosen the one without the hash for my previous versions, but there isn't one for 0.8.4. Are the ones with hashes the correct one to use, and am I right in assuming choosing those will result in _a appended to the version?

[stsewd]

I don't understand, there isn't a 0.8.4 version now and just 0.8.4_a? If so, try disabling that (or both) and rebuilding latest then if you only have one tag named 0.8.4 (no branch named 0.8.4), you should see only a version 0.8.4, you can also try wiping the versions before building it.

[stsewd]

About the hash on the list, the ones that have a hash are usually a tag, the others a branch.

[JadeMatrix]

Yes, there was never a 0.8.4, only 0.8.4_a, which is the one I tried disabling then re-enabling after rebuilding latest. For previous versions I have non-_a versions available, though these may be artifacts of having built docs while the version was in development. Since RTD never picked up on my latest version branch for some reason, that may be why there is no 0.8.4 version left over.

I'll try re-creating the branch temporarily to see if RTD sees it.

EDIT: That seemed to work — I now have a 0.8.4 version built & public. Does RTD need latest built to pull new branch information? That may have been what I missed this time.

[stsewd]

Does RTD need latest built to pull new branch information?

Yes, you need to build the latest branch for rtd to pull new branches/tags, and sometimes the local repo gets confused when forcing tags so is better to wipe the latest version and rebuilding to get a clean information.

[stsewd]

Closing this as the original issue was solved, feel free to reopen if you consider.