Add alias support to version automation

[agjohnson]

In #4001 we started by adding version automation rules to enable new versions.

In this next phase, we will address the use case of automation of version aliases. Prior to this, we might need to refactor how we are managing version alias, and potentially more widely support alias management in our UI.

Example use cases here are:

• User want to set up aliases for minor versions that point to bugfix releases. For instance, a project has 1.0, 1.1, and 2.0 versions active in docs. On release of 2.0.5, the 2.0 alias will automatically repoint to this new tag
• User has an odd branch naming convention, wants to automate adding versions derived from these branch names. For instance, project repository uses major version branches for backporting use and wants version-3.0 to show up as 3.0 automatically.

Some rule example psuedo logic are:

• On [Regex match /2.1.[\d+]/], [Set alias 2.1]
• On [Regex match /([\d+]).([\d+]).[\d+]/], [Set alias {match[0]}.{match[1]}]

Work

• Add an action "Set alias". This action supports some templating, such as the docker hub version automation -- {major}, {minor}, {\1} (regex grouping), etc
• Add UI pieces for rules, if anything new is required in our UI

[stsewd]

Another use case is for users that have versions not compatible with pep 440, instead of renaming all of their versions, they can just rename the slug on rtd and automate this with automation rules. We want to allow users to edit the version slug first.

[helderco]

This seems like the right fix for my use case, let me know if this is true.

I have a python library in a monorepo with components in other languages. For this library, new versions are released by pushing a new sdk/python/v<semver> tag.

Would this feature allow extracting the semver from the tag and use that? Would it also work to set stable?

[stsewd]

This seems like the right fix for my dagger/dagger#3767, let me know if this is true.
Would this feature allow extracting the semver from the tag and use that?

Yes, if implemented, this would solve your problem. Thanks for commenting your use case!

[thibaudcolas]

If I’m not mistaken, what’s described here is what’s been done manually as a support task for Django over the years: #11341; #10748; #9906; #9525; #8520; etc

@stsewd is this something you would be prepared to do for other projects as a support task, or should we wait for this to be officially supported?

We’re in the exact same situation as Django for Wagtail. We currently publish versioned docs with tags, and we need to switch to branches so we can update docs of past versions (our Sphinx theme has compatibility issues with the new Read the Docs addons). And likely stop publishing separate docs per patch release. So we’d want stable/5.1.x to be aliased to 5.1.x (or possibly 5.1, TBC).

[stsewd]

@thibaudcolas we will likely first allow users to change the slug or create an alias manually #9684 before adding an automation rule. But these issues are still pending some decisions, you can request changing your version slug by emailing us to support, just note that any existing version with the old slug will 404, and you need to trigger a new build on the branch/tag that was renamed.

[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.

[Jackenmen]

You can't change the slug of the latest and stable versions that are managed by RTD.

Does this mean that this feature won't yet allow, say, to have a branch named stable-docs and have it appear under project.readthedocs.io/en/stable/?

[stsewd]

Does this mean that this feature won't yet allow, say, to have a branch named stable-docs and have it appear under project.readthedocs.io/en/stable/?

Good question. Haven't tested it yet, but it should be possible, but not straightforward to do. If RTD already created a version named latest or stable automatically (marked as machine created), then you'll need to do a couple of steps to remove the "machine" mark from those, and then rename latest/stable to something else, and then rename your other version to use that name.

Since we already allow users to override stable/latest by creating a branch/tag with that name, I think it's valid to allow doing the change from the form, it would be required for user to first disable the RTD latest/stable version, or maybe do that automatically, but show a big warning.

[Jackenmen]

If it were to require disabling something first, would it be possible to add an authenticated API endpoint for doing that?

My intended workflow is to, when I need to backport some documentation change, create a stable-docs branch, make that RTD stable automatically (either because RTD does it or because I called some API endpoint) and commit the backported changes. Once a new release is cut (tag is created), I would want to automatically switch stable to a build from that tag, while leaving the stable-docs branch up there just in case I need it for something. Pushing the stable-docs branch's state to a different branch name and then removing it is probably also acceptable for my workflow so switching what stable refers to can be done either by RTD or by me calling some API endpoint.

To be entirely fair, I'm not sure if this is the most relevant issue to mention in since I know there's also #5319 but it's at least vaguely related and continues the conversation I already started here, I can repost elsewhere if needed 😄

[thibaudcolas]

@stsewd thanks for the update! I think we’d be interested to try this out for sphinx-wagtail-theme and for wagtail.

All the implementation choices you mentioned make sense. For us I think #11979 would also be needed? But we can confirm once we’ve tried this out I think. In particular, since we want the slug to be more user-friendly than the git branch name, we’d also want the version label inside the Addons picker to be user-friendly (most likely matching the custom slug 1:1).

[stsewd]

@thibaudcolas done!

[thibaudcolas]

Finally got around to trying this – it seems to already work better than I was expecting!

See for example Wagtail’s 6.4 slug, which used to be stable-6.4.x, which is a branch build of stable/6.4.x in GitHub. Proceeding with this would allow us to transition away from tag builds, replacing v6.4 and other tags up to v6.4.3 with a single docs build with a stable slug.

And it’s not just in the URL, it also looks like what we were expecting in the Addons:

---

I wasn’t able to test the sort order of the versions in this list yet. In our case we would want "latest stable [version-specific branch and tags builds, mixed together, in the order of the version number]". I’ll need to try this out on sphinx-wagtail-theme.