Automation rules: add delete version action (#7644)

Currently we automatically delete inactive versions
when they are deleted from the repository.

If the version is active we keep it,
and users must deactivate it manually.

With this rule users can automate that.
Default versions can't deactivate it,
users must change the default version first.

This is the only rule that is run when a version is deleted.

Closes #7637

Co-authored-by: Manuel Kaufmann <[email protected]>

Author: stsewd

docs/automation-rules.rst

@@ -61,6 +61,16 @@ Currently, the following actions are available:
   i.e. the version of your project that `/` redirects to.
   See more in :ref:`automatic-redirects:Root URL`.
   It also activates and builds the version.
+- **Delete version**: When a branch or tag is deleted from your repository,
+  Read the Docs will delete it *only if isn't active*.
+  This action allows you to delete *active* versions when a branch or tag is deleted from your repository.
+
+  .. note::
+
+     The default version isn't deleted even if it matches a rule.
+     You can use the ``Set version as default`` action to change the default version
+     before deleting the current one.
+
 
 .. note::
 
@@ -99,6 +109,13 @@ Activate only new branches that belong to the ``1.x`` release
 - Version type: ``Branch``
 - Action: ``Activate version``
 
+Delete an active version when a branch is deleted
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- Match: ``Any version``
+- Version type: ``Branch``
+- Action: ``Delete version``
+
 Set as default new tags that have the ``-stable`` or ``-release`` suffix
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

readthedocs/api/v2/utils.py

@@ -14,7 +14,7 @@
     STABLE_VERBOSE_NAME,
     TAG,
 )
-from readthedocs.builds.models import Version
+from readthedocs.builds.models import RegexAutomationRule, Version
 
 log = logging.getLogger(__name__)
 
@@ -139,8 +139,7 @@ def _set_or_create_version(project, slug, version_id, verbose_name, type_):
     return version, False
 
 
-def delete_versions_from_db(project, version_data):
-    """Delete all versions not in the current repo."""
+def _get_deleted_versions_qs(project, version_data):
     # We use verbose_name for tags
     # because several tags can point to the same identifier.
     versions_tags = [
@@ -153,7 +152,6 @@ def delete_versions_from_db(project, version_data):
     to_delete_qs = (
         project.versions
         .exclude(uploaded=True)
-        .exclude(active=True)
         .exclude(slug__in=NON_REPOSITORY_VERSIONS)
     )
 
@@ -165,33 +163,63 @@ def delete_versions_from_db(project, version_data):
         type=BRANCH,
         identifier__in=versions_branches,
     )
+    return to_delete_qs
+
+
+def delete_versions_from_db(project, version_data):
+    """
+    Delete all versions not in the current repo.
 
-    ret_val = set(to_delete_qs.values_list('slug', flat=True))
-    if ret_val:
+    :returns: The slug of the deleted versions from the database.
+    """
+    to_delete_qs = (
+        _get_deleted_versions_qs(project, version_data)
+        .exclude(active=True)
+    )
+    deleted_versions = set(to_delete_qs.values_list('slug', flat=True))
+    if deleted_versions:
         log.info(
             '(Sync Versions) Deleted Versions: project=%s, versions=[%s]',
-            project.slug, ' '.join(ret_val),
+            project.slug, ' '.join(deleted_versions),
         )
         to_delete_qs.delete()
 
-    return ret_val
+    return deleted_versions
+
+
+def get_deleted_active_versions(project, version_data):
+    """Return the slug of active versions that were deleted from the repository."""
+    to_delete_qs = (
+        _get_deleted_versions_qs(project, version_data)
+        .filter(active=True)
+    )
+    return set(to_delete_qs.values_list('slug', flat=True))
 
 
-def run_automation_rules(project, versions_slug):
+def run_automation_rules(project, added_versions, deleted_active_versions):
     """
     Runs the automation rules on each version.
 
     The rules are sorted by priority.
 
+    :param added_versions: Slugs of versions that were added.
+    :param deleted_active_versions: Slugs of active versions that were deleted from the repository.
+
     .. note::
 
        Currently the versions aren't sorted in any way,
        the same order is keeped.
     """
-    versions = project.versions.filter(slug__in=versions_slug)
-    rules = project.automation_rules.all()
-    for version, rule in itertools.product(versions, rules):
-        rule.run(version)
+    class_ = RegexAutomationRule
+    actions = [
+        (added_versions, class_.allowed_actions_on_create),
+        (deleted_active_versions, class_.allowed_actions_on_delete),
+    ]
+    for versions_slug, allowed_actions in actions:
+        versions = project.versions.filter(slug__in=versions_slug)
+        rules = project.automation_rules.filter(action__in=allowed_actions)
+        for version, rule in itertools.product(versions, rules):
+            rule.run(version)
 
 
 class RemoteOrganizationPagination(PageNumberPagination):

readthedocs/api/v2/views/model_views.py

@@ -53,6 +53,7 @@
     RemoteOrganizationPagination,
     RemoteProjectPagination,
     delete_versions_from_db,
+    get_deleted_active_versions,
     run_automation_rules,
     sync_versions_to_db,
 )
@@ -220,6 +221,7 @@ def sync_versions(self, request, **kwargs):  # noqa: D205
                 )
                 added_versions.update(ret_set)
             deleted_versions = delete_versions_from_db(project, data)
+            deleted_active_versions = get_deleted_active_versions(project, data)
         except Exception as e:
             log.exception('Sync Versions Error')
             return Response(
@@ -233,7 +235,7 @@ def sync_versions(self, request, **kwargs):  # noqa: D205
             # The order of added_versions isn't deterministic.
             # We don't track the commit time or any other metadata.
             # We usually have one version added per webhook.
-            run_automation_rules(project, added_versions)
+            run_automation_rules(project, added_versions, deleted_active_versions)
         except Exception:
             # Don't interrupt the request if something goes wrong
             # in the automation rules.

readthedocs/builds/automation_actions.py

@@ -8,9 +8,13 @@
 - action_arg: An additional argument to apply the action
 """
 
+import logging
+
 from readthedocs.core.utils import trigger_build
 from readthedocs.projects.constants import PRIVATE, PUBLIC
 
+log = logging.getLogger(__name__)
+
 
 def activate_version(version, match_result, action_arg, *args, **kwargs):
     """
@@ -62,3 +66,14 @@ def set_private_privacy_level(version, match_result, action_arg, *args, **kwargs
     """Sets the privacy_level of the version to private."""
     version.privacy_level = PRIVATE
     version.save()
+
+
+def delete_version(version, match_result, action_arg, *args, **kwargs):
+    """Delete a version if isn't marked as the default version."""
+    if version.project.default_version == version.slug:
+        log.info(
+            "Skipping deleting default version. project=%s version=%s",
+            version.project.slug, version.slug,
+        )
+        return
+    version.delete()

readthedocs/builds/migrations/0028_add_delete_version_action.py

@@ -0,0 +1,18 @@
+# Generated by Django 2.2.16 on 2020-11-05 19:26
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('builds', '0027_add_privacy_level_automation_rules'),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name='versionautomationrule',
+            name='action',
+            field=models.CharField(choices=[('activate-version', 'Activate version'), ('hide-version', 'Hide version'), ('make-version-public', 'Make version public'), ('make-version-private', 'Make version private'), ('set-default-version', 'Set version as default'), ('delete-version', 'Delete version (on branch/tag deletion)')], help_text='Action to apply to matching versions', max_length=32, verbose_name='Action'),
+        ),
+    ]

readthedocs/builds/models.py

@@ -947,6 +947,7 @@ class VersionAutomationRule(PolymorphicModel, TimeStampedModel):
     """Versions automation rules for projects."""
 
     ACTIVATE_VERSION_ACTION = 'activate-version'
+    DELETE_VERSION_ACTION = 'delete-version'
     HIDE_VERSION_ACTION = 'hide-version'
     MAKE_VERSION_PUBLIC_ACTION = 'make-version-public'
     MAKE_VERSION_PRIVATE_ACTION = 'make-version-private'
@@ -958,8 +959,12 @@ class VersionAutomationRule(PolymorphicModel, TimeStampedModel):
         (MAKE_VERSION_PUBLIC_ACTION, _('Make version public')),
         (MAKE_VERSION_PRIVATE_ACTION, _('Make version private')),
         (SET_DEFAULT_VERSION_ACTION, _('Set version as default')),
+        (DELETE_VERSION_ACTION, _('Delete version (on branch/tag deletion)')),
     )
 
+    allowed_actions_on_create = {}
+    allowed_actions_on_delete = {}
+
     project = models.ForeignKey(
         Project,
         related_name='automation_rules',
@@ -1052,14 +1057,17 @@ def match(self, version, match_arg):
 
     def apply_action(self, version, match_result):
         """
-        Apply the action from allowed_actions.
+        Apply the action from allowed_actions_on_*.
 
         :type version: readthedocs.builds.models.Version
         :param any match_result: Additional context from the match operation
         :raises: NotImplementedError if the action
                  isn't implemented or supported for this rule.
         """
-        action = self.allowed_actions.get(self.action)
+        action = (
+            self.allowed_actions_on_create.get(self.action)
+            or self.allowed_actions_on_delete.get(self.action)
+        )
         if action is None:
             raise NotImplementedError
         action(version, match_result, self.action_arg)
@@ -1166,14 +1174,18 @@ class RegexAutomationRule(VersionAutomationRule):
 
     TIMEOUT = 1  # timeout in seconds
 
-    allowed_actions = {
+    allowed_actions_on_create = {
         VersionAutomationRule.ACTIVATE_VERSION_ACTION: actions.activate_version,
         VersionAutomationRule.HIDE_VERSION_ACTION: actions.hide_version,
         VersionAutomationRule.MAKE_VERSION_PUBLIC_ACTION: actions.set_public_privacy_level,
         VersionAutomationRule.MAKE_VERSION_PRIVATE_ACTION: actions.set_private_privacy_level,
         VersionAutomationRule.SET_DEFAULT_VERSION_ACTION: actions.set_default_version,
     }
 
+    allowed_actions_on_delete = {
+        VersionAutomationRule.DELETE_VERSION_ACTION: actions.delete_version,
+    }
+
     class Meta:
         proxy = True
 

readthedocs/rtd_tests/tests/test_automation_rules.py

@@ -1,4 +1,5 @@
 from unittest import mock
+
 import pytest
 from django_dynamic_fixture import get
 
@@ -9,12 +10,12 @@
     SEMVER_VERSIONS,
     TAG,
 )
-from readthedocs.projects.constants import PUBLIC, PRIVATE
 from readthedocs.builds.models import (
     RegexAutomationRule,
     Version,
     VersionAutomationRule,
 )
+from readthedocs.projects.constants import PRIVATE, PUBLIC
 from readthedocs.projects.models import Project
 
 
@@ -183,6 +184,53 @@ def test_action_activation(self, trigger_build):
         assert version.active is True
         trigger_build.assert_called_once()
 
+    @pytest.mark.parametrize('version_type', [BRANCH, TAG])
+    def test_action_delete_version(self, version_type):
+        slug = 'delete-me'
+        version = get(
+            Version,
+            slug=slug,
+            verbose_name=slug,
+            project=self.project,
+            active=True,
+            type=version_type,
+        )
+        rule = get(
+            RegexAutomationRule,
+            project=self.project,
+            priority=0,
+            match_arg='.*',
+            action=VersionAutomationRule.DELETE_VERSION_ACTION,
+            version_type=version_type,
+        )
+        assert rule.run(version) is True
+        assert not self.project.versions.filter(slug=slug).exists()
+
+    @pytest.mark.parametrize('version_type', [BRANCH, TAG])
+    def test_action_delete_version_on_default_version(self, version_type):
+        slug = 'delete-me'
+        version = get(
+            Version,
+            slug=slug,
+            verbose_name=slug,
+            project=self.project,
+            active=True,
+            type=version_type,
+        )
+        self.project.default_version = slug
+        self.project.save()
+
+        rule = get(
+            RegexAutomationRule,
+            project=self.project,
+            priority=0,
+            match_arg='.*',
+            action=VersionAutomationRule.DELETE_VERSION_ACTION,
+            version_type=version_type,
+        )
+        assert rule.run(version) is True
+        assert self.project.versions.filter(slug=slug).exists()
+
     def test_action_set_default_version(self):
         version = get(
             Version,