Use common URL for each point release / maintenance branch

[davidism]

The Flask docs present versions like "0.12" and "1.0", but behind the scenes these are actually the "0.12-maintenance" and "1.0-maintenance" branches. This is so we don't create separate URLs for every minor update, as well as being able to correct mistakes in the docs without making a new tag and release.

So http://flask.pocoo.org/docs/1.0/ is the URL for 1.0, 1.0.1, 1.0.2, and any unreleased minor changes in the 1.0-maintenance branch.

I think what this means is I want to be able to make the URL for 1.0-maintenance branch "/1.0/", and turn off builds for tags.

[stsewd]

Maybe the same as #893?

and turn off builds for tags.

I think you can deactivate each tag version in the Versions section.

[ericholscher]

Yea, we should add support for aliases for versions, which would solve this use case.

[ericholscher]

We have aliases for subprojects, so it would be a similar pattern, except just live on the Version object.

[davidism]

As part of the alias, I'd also like to be able to set the version and release values for the branch. So instead of Sphinx seeing version = '1.0.3-dev' (which is what the branch technically is), it should see 1.0.2, since that's the closeset release to that branch.

[davidfischer]

My plan here is to have the ability to create an alias for a version. For Flask, as an example, this would be done on this page.

The Version API actually already has a "verbose name" and "slug" and possibly this is just a matter of making those editable. Otherwise, possibly it could just be an additional field.

[davidfischer]

I'm looking at possibly implementing some parts of #4001 in order to accomplish this.

[ericholscher]

The Version API actually already has a "verbose name" and "slug" and possibly this is just a matter of making those editable. Otherwise, possibly it could just be an additional field.

The primary thing we need to worry about here is syncing from git. Our logic around this is pretty fiddly, so you'd need to double check if the syncing code will change the names back when it encounters them on the FS. It's more likely that it would just create another version with that name, and when they push new code to the branch, it won't update the alias properly. So I think we'll need a bit more complexity here to handle aliases.

[davidfischer]

The primary thing we need to worry about here is syncing from git. Our logic around this is pretty fiddly, so you'd need to double check if the syncing code will change the names back when it encounters them on the FS.

Based on what I'm seeing here, I don't think git will change the names back. It looks to explicitly check the identifier (eg. origin/1.0-maintenance).

[davidfischer]

The end decision here is that we aren't at this time going to allow users to edit version slugs. Aliases and redirects might be implemented in the future although the canonical URL would be based on the version slug.

If projects need us to edit version slugs we can do it and that does just work but it is not desirable.