Clarifications to state vs status

Author: benjaoming

readthedocs/builds/constants.py

@@ -3,6 +3,9 @@
 from django.conf import settings
 from django.utils.translation import gettext_lazy as _
 
+# BUILD_STATE is our *INTERNAL* representation of build states.
+# This is not to be confused with external representations of 'status'
+# that are sent back to Git providers.
 BUILD_STATE_TRIGGERED = "triggered"
 BUILD_STATE_CLONING = "cloning"
 BUILD_STATE_INSTALLING = "installing"
@@ -78,7 +81,9 @@
     STABLE,
 )
 
-# General Build Statuses
+# General build statuses, i.e. the status that is reported back to the
+# user on a Git Provider. This not the same as BUILD_STATE which the internal
+# representation.
 BUILD_STATUS_FAILURE = 'failed'
 BUILD_STATUS_PENDING = 'pending'
 BUILD_STATUS_SUCCESS = 'success'

readthedocs/oauth/services/github.py

@@ -446,8 +446,8 @@ def send_build_status(self, build, commit, status):
         project = build.project
         owner, repo = build_utils.get_github_username_repo(url=project.repo)
 
-        # select the correct state and description.
-        github_build_state = SELECT_BUILD_STATUS[status]["github"]
+        # select the correct status and description.
+        github_build_status = SELECT_BUILD_STATUS[status]["github"]
         description = SELECT_BUILD_STATUS[status]["description"]
         statuses_url = f"https://api.github.com/repos/{owner}/{repo}/statuses/{commit}"
 
@@ -461,15 +461,15 @@ def send_build_status(self, build, commit, status):
         context = f'{settings.RTD_BUILD_STATUS_API_NAME}:{project.slug}'
 
         data = {
-            'state': github_build_state,
-            'target_url': target_url,
-            'description': description,
-            'context': context,
+            "state": github_build_status,
+            "target_url": target_url,
+            "description": description,
+            "context": context,
         }
 
         log.bind(
             project_slug=project.slug,
-            commit_status=github_build_state,
+            commit_status=github_build_status,
             user_username=self.user.username,
             statuses_url=statuses_url,
         )

readthedocs/projects/tasks/builds.py

@@ -429,6 +429,8 @@ def on_failure(self, exc, task_id, args, kwargs, einfo):
         """
         Celery handler to be executed when a task fails.
 
+        Updates build data, adds tasks to send build notifications.
+
         .. note::
 
            Since the task has failed, some attributes from the `self.data`
@@ -520,7 +522,10 @@ def on_failure(self, exc, task_id, args, kwargs, einfo):
             )
 
         # Update build object
-        self.data.build['success'] = False
+        if isinstance(exc, BuildUserSkip):
+            self.data.build["success"] = True
+        else:
+            self.data.build["success"] = False
 
     def get_valid_artifact_types(self):
         """