Versions: let users define algorithm to define `stable`

[humitos]

With the introduction of "sorting algorithms" for the versions in the flyout, @stsewd suggested we could use these algorithms as well to determine the stable version. This would be a really good addition taking into account that our process to determine stable is not clear to users and it's not possible to change it either.

This would be a big refactor and I think there should be some discussions and planning before moving forward with this.

Reference https://github.com/readthedocs/readthedocs.org/pull/11069#pullrequestreview-1849462143 Related:

• https://github.com/readthedocs/readthedocs.org/issues/10785
• https://github.com/readthedocs/readthedocs.org/issues/6415
• https://github.com/readthedocs/readthedocs.org/issues/5319
• https://github.com/readthedocs/readthedocs.org/issues/7219

[agjohnson]

We've also talked about surfacing this as an automation rule, which would be a good home for showing the user and sort of configuration around latest/stable versions.

[astrojuanlu]

So good to see discussion about this ❤️ And it would be fantastic to address #5319 indeed.

One thing that came to mind recently is that, in some cases, I'd love to even get rid of /stable altogether, or at least turn it into a redirection.

The reason is that, for users that are not used to the RTD terminology, reading /stable in the URL and seeing it in the flyout doesn't make obvious that they can change the version of the docs. The moment the version number is written in the URL and shown in the flyout this becomes self-evident.

(Comes from https://github.com/kedro-org/kedro/issues/3741#issuecomment-2020767653)

[humitos]

One thing that came to mind recently is that, in some cases, I'd love to even get rid of /stable altogether, or at least turn it into a redirection.

In case you want to try this approach and provide feedback, you can

1. de-activate stable version
2. create a redirect like /stable/:splat to /page/:splat
3. use an automation rule to match "SemVer versions" and call the action "set version as default"

I haven't tested this, but I think it could work for your use case.

[agjohnson]

This would be a big refactor and I think there should be some discussions and planning before moving forward with this.

If we wanted to add an option for turning off our implicit stable version for projects, one that is not deactivating the stable version, might that help avoid a huge refactor?

I'm wondering if that, combined with surfacing stable in automation rules, gives users a better way to control stable without us having to refactor our stable version code.

I can see how this might be a lot refactoring, but still do think we should be more flexible with the stable version feature. We have talked about some complicated ways of achieving this -- surfacing our implicit rules as automation rules namely -- that are maybe a good end goal but don't necessarily need to be where we start with this either.

[astrojuanlu]

You mean #5319 right? Would love to see it happening!

[agjohnson]

Yeah, I suppose this issue is more about adding more algorithms besides semver. #5319 is more what I've been thinking here, though the idea of surfacing implicit rules as explicit rules can be skipped -- that's just a nice to have feature for later.

I'm putting this one on our discussion list so we can try to come up with a plan and prioritize this, I'd also love to see this control in automation rules.

[humitos]

If we wanted to add an option for turning off our implicit stable version for projects, one that is not deactivating the stable version, might that help avoid a huge refactor?

I think it will be a huge refactor anyways. We will need to add an if in every single place where this magic happens to check if it's enabled/disabled, which I think it's spread all around the code. I'm sure we will end up with a few bugs and edge cases for a season 😄 . @stsewd was the last one working on some code related to this, so he may have more fresh context here.

[astrojuanlu]

I finally tried this https://github.com/readthedocs/readthedocs.org/issues/11183#issuecomment-2032403457

Type: Exact Redirect
From URL: /projects/{subproject}/en/stable/*
To URL: /projects/{subproject}/page/:splat

and seems to be working. And at this point I think I actually prefer /stable to be a redirection, rather than a version.