Version page should show build status + Admin Version auto-build

[ofbeaton]

Feature request 1: The Overview Versions list should show the build status.
Feature request 2: Checking a new version for inclusion should automatically queue it to be built.
Feature request 3: You should not be able to pick a non-built doc.
Feature request 4: 404 for a non-built doc should display "latest" with a warning

Why is there two places to specify default version? In Admin->advanced and Admin->versions

Only one of these should exist.

Got burned today when my docs were not built for half a day after I made a release announcement. Docs were just a giant 404 because I had updated "default version" to a non-built doc.

[agjohnson]

Thanks for the feedback, the version page is planned for a complete overhaul. These would be good changes to work in.

Not sure what the third feature means however, and I think the fourth feature is an anti-pattern. We don't want to blindly redirect to the latest version.

[ofbeaton]

#3 is on the admin -> versions page there is a dropdown for which version to go to. You can select a version that is not built. This breaks your docs.

My scenario was I made a new release on github, the version was imported on readthedocs, I selected as the new default version, and I redirected my users to it using a link, say: http://docs.kadala.ofbeaton.com/en/0.3.0/

It is just a 404. Because it's not built yet. From it you can't find any of my working docs. And in this case if you took off the /en/0.3.0/ it would just redirect to it since I had selected it.

That's what #4 is about, maybe "redirect to stable/latest" is not the right move, but the 404 should show the other versions that ARE built. So they can at least get something.

Essentially everyone who tried to use my library couldn't get help until I fixed it, and I didn't even realize it was broken. Even though I had 2-3 versions built and working fine.

I mean your bookmark use case is the same... if a user bookmarks a specific version, then the person removes it, they get a generic 404, with no ability to select a current version.

[ofbeaton]

So apparently I can't read, because that 404 DOES list the other versions that are built. Apparently I'm blind. Or it was just added, but I am betting it was always there.

As a feature request I would still like it if the 404 matched the readthedocs skins, and people could use the version menu as usual. It wasn't obvious to me, but that doesn't mean it isn't obvious to others...

Anyways, if you agree with and can use some of these suggestions, then great.

[humitos]

Feature request 1: The Overview Versions list should show the build status.

We are currently showing Passed and Failed. It could be improved with red/green colors, though.

Feature request 2: Checking a new version for inclusion should automatically queue it to be built.

Activating a version, automatically trigger a build for it already.

Feature request 3: You should not be able to pick a non-built doc.

We should filter this line by built also,

https://github.com/rtfd/readthedocs.org/blob/4031b9078efba9948301e89c948a236671086d26/readthedocs/projects/forms.py#L417

like,

choices = [(version.slug, version.verbose_name) for version in active if version.built]

Feature request 4: 404 for a non-built doc should display "latest" with a warning
That's what #4 is about, maybe "redirect to stable/latest" is not the right move, but the 404 should show the other versions that ARE built. So they can at least get something.

I do see two different approaches for this. When hitting a 404, we try the redirects from Django and if no redirect is found for that URL, we can do:

1. redirect to the default version adding something like ?redrected_from=v0.72 and use some Javascript to get that querystring and show a warning communicating this.
2. return a dynamic 404 page saying that version was not found but "These are all the current active versions for this project"

[stsewd]

We are currently showing Passed and Failed. It could be improved with red/green colors, though.

We could use the pattern that it's used in the dashboard

Feature request 3: You should not be able to pick a non-built doc.

We should filter this line by built also

I don't understand the first sentence, the second, I think I do, but sometimes we want to rebuild a version, a branch for example.

[humitos]

Feature request 3: You should not be able to pick a non-built doc.

We should filter this line by built also

I don't understand the first sentence, the second, I think I do, but sometimes we want to rebuild a version, a branch for example.

The idea is to not be able to set the "default version" a Version that it's not built yet because if so, when you access the docs you will get all 404s

[humitos]

Feature request 4: 404 for a non-built doc should display "latest" with a warning

This will be achieved by #353 (specific 404) and/or #2551 (general for all the RTD projects).

Removing design decision because the requests are actionable now,

• use the same pattern to show Passed and Failed in the Version list than when listing projects
• do not allow non built Versions as default version

[stsewd]

do not allow non built Versions as default version

Wouldn't that be bad UX? I mean, it would be confused not to see all the versions just because isn't built yet.

[humitos]

I think we could explain that with a text next to it. The thing is that if you choose a non built version as default, your documentation will be broken until that version builts.

[dojutsu-user]

@humitos
I agree with you.

Where do you want to add the text? Can you please raise your thoughts on the attached PR.

[stsewd]

@humitos we should test for projects that are just imported and don't have any build.

[dojutsu-user]

@stsewd
Here it how it looks when I tried with a project that don't have any successful build yet.

>>> from readthedocs.projects.models import Project
>>> Project.objects.get(name__contains='pikachu').get_default_version()
'latest'

It does raises some issues like latest option is not show but it is set as default.

Edit: But I'm +1 on @humitos suggesstion to add some text which will make things clear.

[humitos]

All of the features proposed in the description were already implemented and they are way nicer in the new dashboard: https://beta.readthedocs.org/. Please open a new issue on https://github.com/readthedocs/ext-theme if you have more feedback about the new dashboard 👍🏼