Add latest/stable rules to version automation

[agjohnson]

:new: I am proposing to split this into two phases. This issue originally discussed moving implicit rules to explicit rules. Instead, I think we could start just by surfacing control that can override our implicit rules. My primary want here is user control of stable. The intent is to reduce the work needed to achieve stable automation rules.

Work we started in #4001 and #5318 will be expanded on here. We will refactor latest/stable alias management and make this more explicit to users. Users will be able to manage these aliases and our implicit rules will be surfaced in the UI for user management.

Example of psuedo rule logic we'll support with this:

• On [Most recent commit], [Set alias latest]
• On [Most recent tag/branch], [Set alias stable]

Work

• [ ] Support stable as a target for automation rules
• [ ] Some method to override/disable implicit stable version logic

Front conversations

[stsewd]

I just realized that we have some kind of automation for stable right now.

• If stable is active
• A new version is created and it's a new stable (greater than the previous one)
• If the previous version and stable were active
• The new version is activated too

https://github.com/rtfd/readthedocs.org/blob/78c34c904b347110b2cd545b4b5a80ed526590f7/readthedocs/restapi/views/model_views.py#L229-L237

[agjohnson]

One case where we might need explicit control over stable manipulation is when the project's versioning scheme doesn't quite match semver -- for instance when versions have a v prefix, like v1.2.3. These versions seem to evade our detection of stable from what I can tell.

Maybe a few options here:

• We surface the implicit stable/latest rules as default automation rules for a project. This is a lot of work, but I do like the UX here
• We let the user override our implicit rule by specifying their own stable/latest rules. We don't (yet?) try to backport this to all projects like the previous option. If a project has a stable rule, maybe we short circuit our logic and avoid implicit stable/latest version rlues
• We put special case on our versioning logic to make some of these use cases magically work. The v prefix is super common, so this could be an okay temporary solution for at least that use case.
• Could we add a feature to point stable to the most recently added/activated version?

I suppose I vote the options that turn these implicit rules, or move us closer to turning these implicit rules, into explicit automation rules.

Any other options? @stsewd any opinions on direction here?

[agjohnson]

Hrm plot twist. I set up a test scenario for the case above and it functioned like expected. Incrementing a version v1.2 to v1.3 tag did in fact update stable, unlike the user report that is noticing the opposite. There might be more to the user report or something else, like other active versions, interfering here.

It in fact was enough to enable a tagged version, and add an automation rule activating further v\d.\d tags.

[stsewd]

Think what you are mentioning here was from the bug we had with stable not being updates bc a query was killing the python process.

[agjohnson]

Yup! That was the underlying cause to the issue, so I think your point about stable already having automation still stands.

What do you think about surfacing the latest/stable rules as mock automation rules in the new UI? I'm describing hardcoded, immutable objects. Maybe this is a baby step to offering the rules as configurable automation rules, but at least gives all of the various version logic rules illustrated in one place?

[stsewd]

+1 on making that configurable, that would solve the problem from https://github.com/readthedocs/readthedocs.org/issues/8015#issuecomment-800650527

There is a todo there https://github.com/readthedocs/readthedocs.org/blob/b523a780f5c6c97508cfa8a6fac180b03de52418/readthedocs/builds/tasks.py#L324-L326

I haven't thought about the implementation

[astrojuanlu]

I just found https://github.com/readthedocs/readthedocs.org/issues/5319#issuecomment-470728445 while working on #8473. Would be nice to make this an automation rule.

[helderco]

I have a monorepo and the detected stable version points to another component. The python library in my RTD is released under sdk/python/v<semver> git tags.

Pointing stable to the latest activated version would fix it, no matter if it's semver or not. I'm using an automated rule with custom match to activate the versions, waiting on #5318 to remove that prefix.

[agjohnson]

I was just reminded of this issue and I still think it would be a great UX improvement and could help us solve some issues stemming from the application being not super transparent with how we determine latest/stable.

Perhaps related to this but more likely a separate feature, it would be great to also surface a Version.is_outdated so that the user can control when we notify the reader that they should use a more up to date version.

[pspacek]

Yes please :pray:

As for surfacing Version.is_outdated, that's an excellent idea. E.g. in our project we maintain two different branches numbered like 9.16.z and 9.18.z in parallel. To make the warning accurate we would like to suppress the warning on latest 9.16.43 tag (and label all 9.16.z!=43, 9.17.z, and 9.18.z!=latest) as outdated.

[humitos]

To make the warning accurate we would like to suppress the warning on latest 9.16.43 tag (and label all 9.16.z!=43, 9.17.z, and 9.18.z!=latest) as outdated.

How do think it would be a good UX to communicate this to Read the Docs in a simple way that most users can understand?

[pspacek]

I think the current warning along the lines ~ "you are using outdated versions" is fine. It should be up to the individual projects to decide what is "outdated".

[astrojuanlu]

Would turning latest and stable into explicit automation rules that can be tweaked by users help with things like https://github.com/readthedocs/readthedocs.org/issues/10674 or help monorepos figure out a versioning method that works for them (given that the rules for stable assume 1 repo = 1 project)?

cc @maxschulz-COL

[maxschulz-COL]

Would turning latest and stable into explicit automation rules that can be tweaked by users help with things like #10674 or help monorepos figure out a versioning method that works for them (given that the rules for stable assume 1 repo = 1 project)?

cc @maxschulz-COL

I can only second the above! This would help us a lot!

[maxschulz-COL]

Hey lovely people - can report that on Vizro, we have come back to this, and we would still be excited for this feature :)