Add models for automation rules

readthedocs/builds/admin.py

@@ -1,15 +1,23 @@
-# -*- coding: utf-8 -*-
-
 """Django admin interface for `~builds.models.Build` and related models."""
 
 from django.contrib import admin, messages
 from guardian.admin import GuardedModelAdmin
-
-from readthedocs.builds.models import Build, BuildCommandResult, Version
+from polymorphic.admin import (
+    PolymorphicChildModelAdmin,
+    PolymorphicParentModelAdmin,
+)
+
+from readthedocs.builds.models import (
+    Build,
+    BuildCommandResult,
+    RegexAutomationRule,
+    Version,
+    VersionAutomationRule,
+)
 from readthedocs.core.utils import trigger_build
+from readthedocs.core.utils.general import wipe_version_via_slugs
 from readthedocs.projects.models import HTMLFile
 from readthedocs.search.utils import _indexing_helper
-from readthedocs.core.utils.general import wipe_version_via_slugs
 
 
 class BuildCommandResultInline(admin.TabularInline):
@@ -48,7 +56,6 @@ def version_name(self, obj):
 
 
 class VersionAdmin(GuardedModelAdmin):
-    search_fields = ('slug', 'project__name')
     list_display = (
         'slug',
         'type',
@@ -135,5 +142,23 @@ def wipe_version(self, request, queryset):
     wipe_version.short_description = 'Wipe version from ES'
 
 
+@admin.register(RegexAutomationRule)
+class RegexAutomationRuleAdmin(PolymorphicChildModelAdmin, admin.ModelAdmin):
+    base_model = RegexAutomationRule
+
+
+@admin.register(VersionAutomationRule)
+class VersionAutomationRuleAdmin(PolymorphicParentModelAdmin, admin.ModelAdmin):
+    base_model = VersionAutomationRule
+    list_display = (
+        'project',
+        'priority',
+        'match_arg',
+        'action',
+        'version_type',
+    )
+    child_models = (RegexAutomationRule,)
+
+
 admin.site.register(Build, BuildAdmin)
 admin.site.register(Version, VersionAdmin)

readthedocs/builds/automation_actions.py

@@ -0,0 +1,20 @@
+"""
+Actions used for the automation rules.
+
+Each function will receive the following args:
+
+- version: The version object where the action will be applied
+- match_result: The result from the match option
+- action_arg: An additional argument to apply the action
+"""
+
+
+def activate_version(version, match_result, action_arg, *args, **kwargs):
+    version.active = True
+    version.save()
+
+
+def set_default_version(version, match_result, action_arg, *args, **kwargs):
+    project = version.project
+    project.default_version = version.verbose_name
+    project.save()

readthedocs/builds/migrations/0007_add-automation-rules.py

@@ -0,0 +1,53 @@
+# -*- coding: utf-8 -*-
+# Generated by Django 1.11.20 on 2019-04-25 23:04
+from __future__ import unicode_literals
+
+from django.db import migrations, models
+import django.db.models.deletion
+import django_extensions.db.fields
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('projects', '0042_increase_env_variable_value_max_length'),
+        ('contenttypes', '0002_remove_content_type_name'),
+        ('builds', '0006_add_config_field'),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='VersionAutomationRule',
+            fields=[
+                ('id', models.AutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('created', django_extensions.db.fields.CreationDateTimeField(auto_now_add=True, verbose_name='created')),
+                ('modified', django_extensions.db.fields.ModificationDateTimeField(auto_now=True, verbose_name='modified')),
+                ('priority', models.IntegerField(help_text='A lower number (0) means a higher priority', verbose_name='Rule priority')),
+                ('match_arg', models.CharField(help_text='Value used for the rule to match the version', max_length=255, verbose_name='Match argument')),
+                ('action', models.CharField(choices=[('activate-version', 'Activate version on match'), ('set-default-version', 'Set as default version on match')], max_length=32, verbose_name='Action')),
+                ('action_arg', models.CharField(blank=True, help_text='Value used for the action to perfom an operation', max_length=255, null=True, verbose_name='Action argument')),
+                ('version_type', models.CharField(choices=[('branch', 'Branch'), ('tag', 'Tag'), ('unknown', 'Unknown')], max_length=32, verbose_name='Version type')),
+                ('polymorphic_ctype', models.ForeignKey(editable=False, null=True, on_delete=django.db.models.deletion.CASCADE, related_name='polymorphic_builds.versionautomationrule_set+', to='contenttypes.ContentType')),
+                ('project', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='automation_rules', to='projects.Project')),
+            ],
+            options={
+                'ordering': ('priority', '-modified', '-created'),
+                'manager_inheritance_from_future': True,
+            },
+        ),
+        migrations.CreateModel(
+            name='RegexAutomationRule',
+            fields=[
+            ],
+            options={
+                'proxy': True,
+                'manager_inheritance_from_future': True,
+                'indexes': [],
+            },
+            bases=('builds.versionautomationrule',),
+        ),
+        migrations.AlterUniqueTogether(
+            name='versionautomationrule',
+            unique_together=set([('project', 'priority')]),
+        ),
+    ]

readthedocs/builds/models.py

@@ -12,10 +12,13 @@
 from django.utils import timezone
 from django.utils.translation import ugettext
 from django.utils.translation import ugettext_lazy as _
+from django_extensions.db.models import TimeStampedModel
 from guardian.shortcuts import assign
 from jsonfield import JSONField
+from polymorphic.models import PolymorphicModel
 from taggit.managers import TaggableManager
 
+import readthedocs.builds.automation_actions as actions
 from readthedocs.config import LATEST_CONFIGURATION_VERSION
 from readthedocs.core.utils import broadcast
 from readthedocs.projects.constants import (
@@ -701,3 +704,119 @@ def run_time(self):
         if self.start_time is not None and self.end_time is not None:
             diff = self.end_time - self.start_time
             return diff.seconds
+
+
+class VersionAutomationRule(PolymorphicModel, TimeStampedModel):
+
+    """Versions automation rules for projects."""
+
+    ACTIVATE_VERSION_ACTION = 'activate-version'
+    SET_DEFAULT_VERSION_ACTION = 'set-default-version'
+    ACTIONS = (
+        (ACTIVATE_VERSION_ACTION, _('Activate version on match')),
+        (SET_DEFAULT_VERSION_ACTION, _('Set as default version on match')),
+    )
+
+    project = models.ForeignKey(
+        Project,
+        related_name='automation_rules',
+        on_delete=models.CASCADE,
+    )
+    priority = models.IntegerField(
+        _('Rule priority'),
+        help_text=_('A lower number (0) means a higher priority'),
+    )
+    match_arg = models.CharField(
+        _('Match argument'),
+        help_text=_('Value used for the rule to match the version'),
+        max_length=255,
+    )
+    action = models.CharField(
+        _('Action'),
+        max_length=32,
+        choices=ACTIONS,
+    )
+    action_arg = models.CharField(
+        _('Action argument'),
+        help_text=_('Value used for the action to perfom an operation'),
+        max_length=255,
+        null=True,
+        blank=True,
+    )
+    version_type = models.CharField(
+        _('Version type'),
+        max_length=32,
+        choices=VERSION_TYPES,
+    )
+
+    class Meta:
+        unique_together = (('project', 'priority'),)
+        ordering = ('priority', '-modified', '-created')
+
+    def run(self, version, *args, **kwargs):
+        """
+        Run an action if `version` matches the rule.
+
+        :type version: readthedocs.builds.models.Version
+        :returns: True if the action was performed
+        """
+        if version.type == self.version_type:
+            match, result = self.match(version, self.match_arg)
+            if match:
+                self.apply_action(version, result)
+                return True
+        return False
+
+    def match(self, version, match_arg):
+        """
+        Returns True and the match result if the version matches the rule.
+
+        :type version: readthedocs.builds.models.Version
+        :param str match_arg: Additional argument to perform the match
+        :returns: A tuple of (boolean, match_resul).
+                  The result will be passed to `apply_action`.
+        """
+        return False, None
+
+    def apply_action(self, version, match_result):
+        """
+        Apply the action from allowed_actions.
+
+        :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)
+        if action is None:
+            raise NotImplementedError
+        action(version, match_result, self.action_arg)
+
+    def __str__(self):
+        class_name = self.__class__.__name__
+        return (
+            f'({self.priority}) '
+            f'{class_name}/{self.get_action_display()} '
+            f'for {self.project.slug}:{self.get_version_type_display()}'
+        )
+
+
+class RegexAutomationRule(VersionAutomationRule):
+
+    allowed_actions = {
+        VersionAutomationRule.ACTIVATE_VERSION_ACTION: actions.activate_version,
+        VersionAutomationRule.SET_DEFAULT_VERSION_ACTION: actions.set_default_version,
+    }
+
+    class Meta:
+        proxy = True
+
+    def match(self, version, match_arg):
+        try:
+            match = re.search(
+                match_arg, version.verbose_name
+            )
+            return bool(match), match
+        except Exception as e:
+            log.info('Error parsing regex: %s', e)
+            return False, None

readthedocs/projects/models.py

@@ -911,7 +911,7 @@ def update_stable_version(self):
         """
         Returns the version that was promoted to be the new stable version.
 
-        Return ``None`` if no update was mode or if there is no version on the
+        Return ``None`` if no update was made or if there is no version on the
         project that can be considered stable.
         """
         versions = self.versions.all()

readthedocs/restapi/utils.py

@@ -2,6 +2,7 @@
 
 """Utility functions that are used by both views and celery tasks."""
 
+import itertools
 import logging
 
 from rest_framework.pagination import PageNumberPagination
@@ -160,6 +161,13 @@ def delete_versions(project, version_data):
     return set()
 
 
+def run_automation_rules(project, versions_slug):
+    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 RemoteOrganizationPagination(PageNumberPagination):
     page_size = 25
 

readthedocs/restapi/views/model_views.py

@@ -8,7 +8,7 @@
 from django.shortcuts import get_object_or_404
 from django.template.loader import render_to_string
 from rest_framework import decorators, permissions, status, viewsets
-from rest_framework.parsers import MultiPartParser, JSONParser, FormParser
+from rest_framework.parsers import JSONParser, MultiPartParser
 from rest_framework.renderers import BaseRenderer, JSONRenderer
 from rest_framework.response import Response
 
@@ -215,6 +215,17 @@ def sync_versions(self, request, **kwargs):  # noqa: D205
                 status=status.HTTP_400_BAD_REQUEST,
             )
 
+        try:
+            api_utils.run_automation_rules(project, added_versions)
+        except Exception:
+            # Don't interrupt the request if something goes wrong
+            # in the automation rules.
+            log.exception(
+                'Failed to execute automation rules for [%s]: %s',
+                project.slug, added_versions
+            )
+
+        # TODO: move this to an automation rule
         promoted_version = project.update_stable_version()
         new_stable = project.get_stable_version()
         if promoted_version and new_stable and new_stable.active: