Version: document how to change the version slug and expose it to everyone (#12096)

Closes #11971

Author: stsewd

docs/user/faq.rst

@@ -88,10 +88,8 @@ We have documented how to set this up in :doc:`/reference/robots`.
 How do I change the version slug of my project?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-We don't support allowing folks to change the slug for their versions.
-But you can rename the branch/tag to achieve this.
-If that isn't enough,
-you can request the change sending an email to [email protected].
+You can change the slug of your versions from the versions tab of your project,
+see :ref:`versions:Version URL identifier (slug)` for more information.
 
 
 What commit of Read the Docs is in production?

docs/user/versions.rst

@@ -88,6 +88,39 @@ all of the artifacts of your version will be deleted and a ``404 Not Found`` pag
 
 You can change the state for each version of your documentation in the :guilabel:`Versions` tab of your project.
 
+Version URL identifier (slug)
+-----------------------------
+
+Each version of your project has a unique URL identifier (slug).
+This identifier is used to reference the version in your documentation, :term:`dashboard`, and :doc:`API </api/index>`.
+
+A version slug is automatically generated from the name of the branch or tag in your repository,
+some special characters like spaces and ``/`` are replaced with a dash (``-``), and the name is lowercased.
+If the resulting slug collides with another one, a suffix is added (``_a``, ``_b``, etc.).
+
+You can change the slug of a version in :ref:`the versions tab of your project <versions:Managing your versions>`,
+but you should take the following into account:
+
+- Changing the slug of an active version will result on its previous documentation being deleted, and a new build being triggered.
+  Be careful when renaming active versions, specially old ones that might not build anymore.
+- Any URL referencing your version with the old slug will return a ``404 Not Found`` page.
+  You can use :ref:`an exact redirect <user-defined-redirects:Redirecting an old version to a new one>` to redirect users to the new URL,
+- You may still see the original name of the version in some places,
+  as changing the slug only affects the URL used in your documentation and how the APIs identify that version.
+  `We are considering adding another field to be used for display in the future <https://github.com/readthedocs/readthedocs.org/issues/11979>`__.
+- Sorting of versions in the version selector is done based on the slug,
+  changing the slug of a version may change the order in which they are shown to your users.
+  `We are considering adding another field to be used for sorting in the future <https://github.com/readthedocs/readthedocs.org/issues/11979>`__.
+- You can't change the slug of versions that are managed by Read the Docs, like ``latest`` and ``stable``.
+- Slugs must be unique for each version of your project.
+- The slug can contain lowercase letters, numbers, dashes (``-``), underscores (``_``) and dots (``.``).
+  If you try to use a slug that contains any other character, you'll get an error message with a suggestion of a valid slug.
+
+.. warning::
+
+   Changing the slug of an active version will result on its previous documentation being deleted, and a new build being triggered.
+   Be careful when renaming active versions, specially old ones that might not build anymore.
+
 Disabling versioning completely
 -------------------------------
 

readthedocs/builds/forms.py

@@ -21,7 +21,6 @@
 from readthedocs.builds.models import Version
 from readthedocs.builds.models import VersionAutomationRule
 from readthedocs.builds.version_slug import generate_version_slug
-from readthedocs.projects.models import Feature
 
 
 class VersionForm(forms.ModelForm):
@@ -74,9 +73,6 @@ def __init__(self, *args, **kwargs):
         if self.instance and self.instance.machine:
             self.fields["slug"].disabled = True
 
-        if not self.project.has_feature(Feature.ALLOW_CHANGING_VERSION_SLUG):
-            self.fields.pop("slug")
-
         self.helper = FormHelper()
         self.helper.layout = Layout(*field_sets)
         # We need to know if the version was active before the update.

readthedocs/projects/models.py

@@ -1912,7 +1912,6 @@ def add_features(sender, **kwargs):
     USE_PROXIED_APIS_WITH_PREFIX = "use_proxied_apis_with_prefix"
     ALLOW_VERSION_WARNING_BANNER = "allow_version_warning_banner"
     DONT_SYNC_WITH_REMOTE_REPO = "dont_sync_with_remote_repo"
-    ALLOW_CHANGING_VERSION_SLUG = "allow_changing_version_slug"
 
     # Versions sync related features
     SKIP_SYNC_TAGS = "skip_sync_tags"
@@ -1964,10 +1963,6 @@ def add_features(sender, **kwargs):
             DONT_SYNC_WITH_REMOTE_REPO,
             _("Remote repository: Don't keep project in sync with remote repository."),
         ),
-        (
-            ALLOW_CHANGING_VERSION_SLUG,
-            _("Dashboard: Allow changing the version slug."),
-        ),
         # Versions sync related features
         (
             SKIP_SYNC_BRANCHES,

readthedocs/rtd_tests/tests/test_build_forms.py

@@ -8,18 +8,13 @@
 from readthedocs.builds.forms import VersionForm
 from readthedocs.builds.models import Version
 from readthedocs.projects.constants import PRIVATE, PUBLIC
-from readthedocs.projects.models import Feature, HTMLFile, Project
+from readthedocs.projects.models import HTMLFile, Project
 
 
 class TestVersionForm(TestCase):
     def setUp(self):
         self.user = get(User)
         self.project = get(Project, users=(self.user,), slug="project")
-        get(
-            Feature,
-            feature_id=Feature.ALLOW_CHANGING_VERSION_SLUG,
-            projects=[self.project],
-        )
 
     @override_settings(ALLOW_PRIVATE_REPOS=False)
     def test_default_version_is_active(self):