Rename latest

[astrojuanlu]

What's the problem this feature will solve?

We've had problems in the past with users thinking that latest meant "latest released version" when in fact means "latest development version" (kedro-org/kedro#2823).

Describe the solution you'd like

We'd like to rename latest to something else, for example unreleased (very clear), development (not as good), nightly (still a term used mostly by programmers, not ideal) or similar.

Alternative solutions

@humitos already proposed some things we can do kedro-org/kedro#2823 (comment) but I think none of this fulfills what we want:

• make latest to point to the branch/tag you want from the project's setting by defining the "Default branch"

This repurposes latest to do something else.

• disable latest version completely if you want

We do use latest, so we don't want to disable it. We want to change its name.

• set "Default version" to something different than latest (this is the "Default version" setting)

Our "Default version" is already stable, our problem is not there.

• override latest by creating a branch/tag with that name

This still doesn't cut it.

[humitos]

If you disable latest and make the "Default version" to point to main -- does that resolves the confusion?

[humitos]

You can also create a development (or whatever that communicates that's the "development branch") branch in your project and make "Default version" to point to development. After that, latest can be disabled. Would this be useful for this use case?

[humitos]

We'd like to rename latest to something else

I'm sure this won't be possible in the near future since its name it's pretty hardcoded in multiple places of the code. However, we have been working a lot on El Proxito (the code that serves the documentation) and we are making progress on being able to configure how the URLs look like. So, eventually, it may be possible to "rename a version", but I don't think this will happen soon.

Also, this issue is kind of related of "having an alias" for a version, which has a similar complexity: #6273

[astrojuanlu]

If you disable latest and make the "Default version" to point to main -- does that resolves the confusion?

Not really, we'd still want the default version to be stable, hence the true "latest" released version.

You can also create a development (or whatever that communicates that's the "development branch") branch in your project and make "Default version" to point to development. After that, latest can be disabled. Would this be useful for this use case?

Similarly, we'd want our "Default version" to be stable.

Our development branch is called main like virtually any other GitHub project out there, so enabling the main version still wouldn't help a lot.

As a workaround we could have a unreleased branch be in sync with main and then enable it on RTD, but it's kind of an ugly hack.

Also, this issue is kind of related of "having an alias" for a version, which has a similar complexity: #6273

Yeah changing a version slug (what #4505 started) is exactly what would solve this issue.

I'm sure this won't be possible in the near future since its name it's pretty hardcoded in multiple places of the code.

Understood - feel free to keep this issue open or close it, as you prefer. Thanks @humitos!

[humitos]

Not really, we'd still want the default version to be stable, hence the true "latest" released version.

Ah, OK. Forget about changing the "Default version". I thought you were using latest as "Default version". Never mind what I said about changing the "Default version" at all 😄

As a workaround we could have a unreleased branch be in sync with main and then enable it on RTD, but it's kind of an ugly hack.

Unfortunately, I think this is the only way to achieve your goal currently.

[stsewd]

Hi, we now allow changing the slug of versions. From what I understand you want to change the slug of main to unreleased.

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.

[astrojuanlu]

Yay, thanks @stsewd and team! Could you enable it for kedro for now? I think this should be enough for our purposes

[stsewd]

Done!

[astrojuanlu]

I just set the slug of main to nightly 💯 maybe 1 thing that would make things easier is to see it in the UI:

Like main (nightly) or sth like that.

And another thing, we see the "might be an old version of the docs" banner

but I'd actually love to have a bit of control over that (happy to open new issues if needed)

[stsewd]

maybe @agjohnson has some thoughts about how to distinct that in the UI.

And another thing, we see the "might be an old version of the docs" banner
but I'd actually love to have a bit of control over that (happy to open new issues if needed)

Maybe @humitos has a better answer for that.

[humitos]

And another thing, we see the "might be an old version of the docs" banner

Yeah, the logic for the notification is pretty simple on purpose:

https://github.com/readthedocs/addons/blob/46b2a96f7fba707130e61c8bfc0b03149411fc16/src/notification.js#L241-L250

The nightly slug is detected as a non-stable version and it shows that notification. The only slug we treat as latest version is latest 😄 . You may want to disable this notification for now until we think more about it. We could add other names there maybe like development, nightly, main, dev, etc... or just let the user to define what version should be treat as "latest".

[agjohnson]

I just set the slug of main to nightly 💯 maybe 1 thing that would make things easier is to see it in the UI:

Maybe that should just be "nightly" in the listing? Maybe in that UI it makes sense to have an icon or label, or to note the "main" branch in another way though.

[ktbarrett]

@stsewd I'm not sure if this is the greatest place to request this, but can this feature also be enabled for cocotb?

[stsewd]

@ktbarrett done!