Build: skip build based on commands' exit codes

docs/user/build-customization.rst

@@ -73,6 +73,7 @@ There are some caveats to knowing when using user-defined jobs:
 * Environment variables are expanded in the commands (see :doc:`environment-variables`)
 * Each command is executed in a new shell process, so modifications done to the shell environment do not persist between commands
 * Any command returning non-zero exit code will cause the build to fail immediately
+  (note there is a special exit code to `skip the build <skip-build-based-on-a-condition>`_)
 * ``build.os`` and ``build.tools`` are required when using ``build.jobs``
 
 
@@ -104,6 +105,45 @@ To avoid this, it's possible to unshallow the clone done by Read the Docs:
          - git fetch --unshallow
 
 
+Skip build based on a condition
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+There may be situations where you want to skip a build that was automatically triggered when someone on your team pushed to the repository.
+Skipping builds will allow you to speed up review times and also help us reduce server costs and ultimately our environmental footprint.
+Consider the following scenarios:
+
+* the build depends on an external situation that's not met yet
+* there were no changes on the documentation files
+
+In these scenarios, you can skip the build by executing a custom command that checks for that particular condition
+and exits with code ``439`` to skip it, or ``0`` to continue building the documentation normally.
+If any of the commands return this particular exit code,
+Read the Docs will stop the build immediately,
+mark it as "Cancelled",
+and communicate to your Git platform (GitHub/GitLab) that the build succeeded (green tick ✅) so the pull request is in a mergeable state.
+
+Here is an example that skip build from pull requests when there are no changes to the ``docs/`` folder compared to the ``origin/main`` branch.
+
+.. code-block:: yaml
+   :caption: .readthedocs.yaml
+
+   version: 2
+   build:
+     os: "ubuntu-22.04"
+     tools:
+       python: "3.11"
+     jobs:
+       post_checkout:
+         # Skip building pull requests when there aren't changed in the docs directory.
+         # `--quiet` exits with a 1 when there **are** changes,
+         # so we invert the logic with a !
+         #
+         # If there are no changes (exit 0) we force the command to return with 439.
+         # This is a special exit code on Read the Docs that will cancel the build immediately.
+         - if [ $READTHEDOCS_VERSION_TYPE = "external" ]; then ! git diff --quiet origin/main -- docs/ && exit 439; fi
+
+
+
 Generate documentation from annotated sources with Doxygen
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

readthedocs/doc_builder/constants.py

@@ -1,13 +1,11 @@
-# -*- coding: utf-8 -*-
 
 """Doc build constants."""
 
-import structlog
 import re
 
+import structlog
 from django.conf import settings
 
-
 log = structlog.get_logger(__name__)
 
 PDF_RE = re.compile('Output written on (.*?)')
@@ -30,3 +28,11 @@
 DOCKER_OOM_EXIT_CODE = 137
 
 DOCKER_HOSTNAME_MAX_LEN = 64
+
+# Why 183 exit code?
+#
+# >>> sum(list('skip'.encode('ascii')))
+# 439
+# >>> 439 % 256
+# 183
+RTD_SKIP_BUILD_EXIT_CODE = 183

readthedocs/doc_builder/environments.py

@@ -30,8 +30,9 @@
     DOCKER_SOCKET,
     DOCKER_TIMEOUT_EXIT_CODE,
     DOCKER_VERSION,
+    RTD_SKIP_BUILD_EXIT_CODE,
 )
-from .exceptions import BuildAppError, BuildUserError
+from .exceptions import BuildAppError, BuildUserError, BuildUserSkip
 
 log = structlog.get_logger(__name__)
 
@@ -468,6 +469,8 @@ def run_command_class(
                     project_slug=self.project.slug if self.project else '',
                     version_slug=self.version.slug if self.version else '',
                 )
+            elif build_cmd.exit_code == RTD_SKIP_BUILD_EXIT_CODE:
+                raise BuildUserSkip()
             else:
                 # TODO: for now, this still outputs a generic error message
                 # that is the same across all commands. We could improve this

readthedocs/doc_builder/exceptions.py

@@ -42,6 +42,11 @@ class BuildUserError(BuildBaseException):
     )
 
 
+class BuildUserSkip(BuildUserError):
+    message = gettext_noop("This build was manually skipped using a command exit code.")
+    state = BUILD_STATE_CANCELLED
+
+
 class ProjectBuildsSkippedError(BuildUserError):
     message = gettext_noop('Builds for this project are temporarily disabled')
 

readthedocs/projects/tasks/builds.py

@@ -44,6 +44,7 @@
     BuildCancelled,
     BuildMaxConcurrencyError,
     BuildUserError,
+    BuildUserSkip,
     MkDocsYAMLParseError,
     ProjectBuildsSkippedError,
     YAMLParseError,
@@ -280,6 +281,7 @@ class UpdateDocsTask(SyncRepositoryMixin, Task):
         YAMLParseError,
         BuildCancelled,
         BuildUserError,
+        BuildUserSkip,
         RepositoryError,
         MkDocsYAMLParseError,
         ProjectConfigurationError,
@@ -289,6 +291,7 @@ class UpdateDocsTask(SyncRepositoryMixin, Task):
     exceptions_without_notifications = (
         BuildCancelled,
         BuildMaxConcurrencyError,
+        BuildUserSkip,
         ProjectBuildsSkippedError,
     )
 
@@ -450,8 +453,8 @@ def on_failure(self, exc, task_id, args, kwargs, einfo):
             )
         # Known errors in the user's project (e.g. invalid config file, invalid
         # repository, command failed, etc). Report the error back to the user
-        # using the `message` attribute from the exception itself. Otherwise,
-        # use a generic message.
+        # using the `message` and `state` attributes from the exception itself.
+        # Otherwise, use a generic message and default state.
         elif isinstance(exc, BuildUserError):
             if hasattr(exc, 'message') and exc.message is not None:
                 self.data.build['error'] = exc.message
@@ -490,11 +493,21 @@ def on_failure(self, exc, task_id, args, kwargs, einfo):
             version_type = None
             if self.data.version:
                 version_type = self.data.version.type
+
+            # NOTE: autoflake gets confused here. We need the NOQA for now.
+            status = BUILD_STATUS_FAILURE
+            if isinstance(exc, BuildUserSkip):
+                # The build was skipped by returning the magic exit code,
+                # marked as CANCELLED, but communicated to GitHub as successful.
+                # This is because the PR has to be available for merging when the build
+                # was skipped on purpose.
+                status = BUILD_STATUS_SUCCESS
+
             send_external_build_status(
                 version_type=version_type,
                 build_pk=self.data.build['id'],
                 commit=self.data.build_commit,
-                status=BUILD_STATUS_FAILURE,
+                status=status,
             )
 
         # Update build object