diff --git a/docs/user/faq.rst b/docs/user/faq.rst index 71275c73481..46fe88d7d4a 100644 --- a/docs/user/faq.rst +++ b/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 support@readthedocs.org. +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? diff --git a/docs/user/versions.rst b/docs/user/versions.rst index 19d0cba957f..c306129fa57 100644 --- a/docs/user/versions.rst +++ b/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 `. + +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 `, +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 ` 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 `__. +- 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 `__. +- 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 ------------------------------- diff --git a/readthedocs/builds/forms.py b/readthedocs/builds/forms.py index f8ebf9a5a1a..3cd6411bb69 100644 --- a/readthedocs/builds/forms.py +++ b/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. diff --git a/readthedocs/projects/models.py b/readthedocs/projects/models.py index 87fc0bb30e8..db938ac2eb6 100644 --- a/readthedocs/projects/models.py +++ b/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, diff --git a/readthedocs/rtd_tests/tests/test_build_forms.py b/readthedocs/rtd_tests/tests/test_build_forms.py index edb8288bf62..6cee1720b28 100644 --- a/readthedocs/rtd_tests/tests/test_build_forms.py +++ b/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):