Hosting: allow user to modify branch/tag to url mapping (alias)

[davidism]

When I make a new feature release, I create a branch like 2.2.x for that release. When I stop supporting a feature branch, I want to remove that branch from the repository and replace it with a tag with the same name.

I started doing this for ItsDangerous, MarkupSafe, and Jinja, then stopped when I discovered that Read the Docs creates a name like 1.0.x_b instead of treating the tag and branch as the same slug. Here's the ItsDangerous versions page for example: https://readthedocs.org/projects/itsdangerous/versions/

I would like to be able to clean up / correct this mapping. When I delete the branch and create a tag with the same name (or create the tag first then delete the branch), I want to end up with the same URL.

[davidism]

@davidfischer @ericholscher This is the URL feature I was talking about yesterday.

[davidfischer]

Just to talk a little bit about how this works:

• When RTD builds docs, it syncs your repo and looks at all your tags and branches.
• The slug (our URL-safe database representation) of your branch or tag is unique. We use this in the folder structure of where the built files are stored. It also is used in doc URLs. Essentially, based on the URL, we can figure out the path to where the underlying files are stored.
• Since it's unique, when there is a collision, it appends _a, _b, etc.

So if you create a tag with the same name as a branch, there's definitely going to be a collision. If you deleted the branch first on the repo and removed it from being built by RTD and then added the tag, I suspect that there would be no collision and no problem.

There's a couple options here:

• We could expose the ability to change these slugs. They still have to be unique. There's also a potential foot gun here in that when you change the slug, the docs probably have to rebuild since they won't be in the right place in underlying storage (and we're generally hesitant to just move them).
• We could "just change your slug". This is something we've handled in the past and we can just do that.

[davidism]

I'd like to clean up old branches in Flask, etc. soon. Is it ok if I ping you for now?

[humitos]

@davidfischer you can ping us here, or write to [email protected]. We can help you with this.

[davidfischer]

@davidfischer you can ping us here, or write to [email protected]. We can help you with this.

I think you mean @davidism.

[humitos]

@davidfischer he, yeah. The auto-complete tricked me 😅 . Thanks for pinging the right person 😄

[davidism]

After a bit of experimenting, I've determined that deleting the branch isn't fully handled by the webhook, I need to also trigger a build to get Read the Docs to update the list of available branches. If I don't do that, even if the 2.x branch was deleted and RtD got the webhook notification, it will still create 2.x_a if I push a tag.

I also need to ensure these old branches/tags have appropriate locked requirements and readthedocs.yaml files, otherwise the new build of the old docs will fail. (But that's on me, it's a consequence of very old versions not using pinning, which we always do now.)

So the workflow is basically, create tags locally, delete branches remotely, trigger and finish a build on RtD, push tags, re-enable docs versions. This could probably be improved, but I at least have a way to perform the transition myself without intervention from the RtD team.

[davidism]

It also appears that force pushing a tag causes a race condition where the build is triggered before the ref the tag points to is updated in RtD, so it builds against the old ref the tag pointed to.

This build was triggered after I force pushed the 2.x tag https://readthedocs.org/projects/flask-sqlalchemy/builds/21888357/ and still points to the old ref which fails to build. When I then triggered a build manually for 2.x, it used the correct ref https://readthedocs.org/projects/flask-sqlalchemy/builds/21888584/ and built successfully.

[stsewd]

Hi, we now allow changing the slug of versions. Some notes:

• Changing the slug of an active version will result on its previous documentation being deleted, and a new build being triggered. So be careful when renaming active versions.
• You'll probably want to create a redirect from the old version to the new one (an exact redirect with a wildcard should do it).
• You may still see the old name in some places, as changing the slug only affects the URL and how the APIs identify that version. We are planning on introducing a new field that will control how the version is shown to users and also use that value when sorting the versions (Version: introduce display_name field for sorting and display #11979).
• Sorting of versions makes use of the slug, but I consider that to be more of a bug (Addons: use verbose_name instead of slug for sorting versions #11182), so that may change in the future. But with Version: introduce display_name field for sorting and display #11979 you should have control over that in the future.
• You can't change the slug of the latest and stable versions that are managed by RTD.

This feature is under a feature flag, if you want to try it out let me know the projects you want to test this on.

Also, looks like the problem here is that you needed to delete the old branch first and deactivate the RTD version, for RTD to create the tag with the same slug.