Allow users to change version slug

[stsewd]

Basically what I had in my old design doc #6273

• When changing the slug, we check that it's a valid one (lowercase, only number, etc), in case the slug is not valid, we suggest a valid slug based on the invalid one. Why not just transform the value to a valid slug? Changing the slug is a breaking operation, we want to avoid surprises for the user, if they set a slug to "foo/bar", and then the actual slug is "foo-bar", that's unexpected.
• project is used as s hidden field, following the same pattern we already have for other forms (this way all normal validations like the unique constraint work instead of getting a 500).
• Editing the slug is disabled for machine created versions (stable, latest).
• I'm not restricting the usage of latest or stable, since those will be non-machine created, similar to what a user does already if they name a version stable/latest.
• If a version was active and its slug was changed, the resources attached to the old slug are removed before triggering a new build.
• Cache is always purged after deleting resources from the version.

I was playing with using the "pattern" attribute for the input, so it validates the slug before submitting the form.

But I think showing the error with the suggested slug works better, maybe we can port that to JS instead as a future improvement.

Decisions

• Expose this as a feature flag first, or just document it right away?

TODO

• Allow changing the slug using the API.
• Suggest a redirect from the old slug to the new one.

The idea implemented here comes from this comment: https://github.com/readthedocs/meta/discussions/147#discussioncomment-11789455

ref https://github.com/readthedocs/meta/discussions/147

[humitos]

These changes look very promising, in particular because they are pretty small. I did a quick test locally and I was able to change a slug and serve the documentation under the new URL 🎉

There are some things to consider still:

1. I understand we don't need to touch the sync versions code because it's based on verbose_name and we are not changing that, right?
2. There is no need to save the "old slug" because if required it can be generated based on the verbose_name, as we are doing currently.
3. The dashboard uses verbose_name when mentioning versions; so there is going to be a mismatch for those versions where we change the slug. What would be a good solution for this?
4. Flyout Addon uses slug to sort versions, which will keep working with the changes from this PR. However, I was told that we should use verbose_name there as well. In that case, sorting will break (Addons: use verbose_name instead of slug for sorting versions #11182). Should we keep the sorting by slug then?

[stsewd]

I guess everything is clear after the meeting, just answering for the record

I understand we don't need to touch the sync versions code because it's based on verbose_name and we are not changing that, right?

No, we don't need to.

There is no need to save the "old slug" because if required it can be generated based on the verbose_name, as we are doing currently.

I don't think we need to have access to the old slug at all, we can try to guess the original slug by inferring it from the verbose_name, but that isn't necessarily true as slugs can't be duplicated, so some end with _a suffixes. In any case, if we need the old slug for auditing, using a historical record is a better alternative.

The dashboard uses verbose_name when mentioning versions; so there is going to be a mismatch for those versions where we change the slug. What would be a good solution for this?

I suggested we use another field instead (display_name) that users can change to show in the UI/version selector. That way we don't change verbose_name which is used to keep a one to one match with the versions from the repo.

Flyout Addon uses slug to sort versions, which will keep working with the changes from this PR. However, I was told that we should use verbose_name there as well. In that case, sorting will break (
#11182). Should we keep the sorting by slug then?

I still think we shouldn't use the slug for sorting (the name we show to users in the listings won't match the order), if users want further customization, then sorting should be based on the new display_name field, so the listing matches the order.

[ericholscher]

I don't think we need to have access to the old slug at all, we can try to guess the original slug by inferring it from the verbose_name, but that isn't necessarily true as slugs can't be duplicated, so some end with _a suffixes. In any case, if we need the old slug for auditing, using a historical record is a better alternative.

This could be useful for creating redirects, but perhaps we just do that automatically when they rename the slug?

[stsewd]

This could be useful for creating redirects, but perhaps we just do that automatically when they rename the slug?

My idea would be to create a notification or show the message after the user has done the rename (about a link to create a redirect), we don't need to keep that information forever, specially if the user changes the slug again.

[ericholscher]

This could be useful for creating redirects, but perhaps we just do that automatically when they rename the slug?

My idea would be to create a notification or show the message after the user has done the rename (about a link to create a redirect), we don't need to keep that information forever, specially if the user changes the slug again.

Yea, I think honestly even just putting it in cache and checking for that on the redirects page for a suggested redirect. I'd like to do something similar with the filetreediff stuff and redirect suggestions as well.

[humitos]

Looks good with some suggestions/changes.

[ericholscher]

This looks great to me overall, will let @humitos 👍 it once the last review items are addressed.

[humitos]

Allow changing the slug using the API.
Suggest a redirect from the old slug to the new one.

Can you open issues for these?

[humitos]

Looks great! Thanks for taking into consideration my feedback 👍🏼 We should able to merge and deploy this PR today.

[humitos]

:param version: Version instance. If isn't given,
all resources of project will be deleted.

We need to adapt it to mention "If neither of version and version_slug are given,"

[stsewd]

you always need to pass the version object when passing the version_slug, as the version object has more information about the version like its type that is needed to generate the correct storage paths.