diff --git a/docs/user/build-customization.rst b/docs/user/build-customization.rst index aee84e1ebc2..49681a0959a 100644 --- a/docs/user/build-customization.rst +++ b/docs/user/build-customization.rst @@ -73,7 +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 `_) + (note there is a special exit code to `cancel the build `_) * ``build.os`` and ``build.tools`` are required when using ``build.jobs`` @@ -105,24 +105,14 @@ To avoid this, it's possible to unshallow the clone done by Read the Docs: - git fetch --unshallow -Skip build based on a condition -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Cancel 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: +When a command exits with code ``183``, +Read the Docs will cancel the build immediately. +You can use this approach to cancel builds that you don't want to complete based on some conditional logic. -* 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: +Here is an example that cancels builds from pull requests when there are no changes to the ``docs/`` folder compared to the ``origin/main`` branch: .. code-block:: yaml :caption: .readthedocs.yaml @@ -134,16 +124,20 @@ Here is an example that skip build from pull requests when there are no changes python: "3.11" jobs: post_checkout: - # Skip building pull requests when there aren't changed in the docs directory. + # Cancel 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. + # If there are no changes (exit 0) we force the command to return with 183. # 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 + - | + if [ $READTHEDOCS_VERSION_TYPE = "external" ]; + then + ! git diff --quiet origin/main -- docs/ && exit 183; + fi -This other example shows how to skip a build if the commit message contains ``skip ci`` on it: +This other example shows how to cancel a build if the commit message contains ``skip ci`` on it: .. code-block:: yaml :caption: .readthedocs.yaml @@ -156,8 +150,13 @@ This other example shows how to skip a build if the commit message contains ``sk jobs: post_checkout: # Use `git log` to check if the latest commit contains "skip ci", - # in that case exit the command with 439 to skip the build - - case `git --no-pager log --pretty="tformat:%s" -1` in *"skip ci"*) exit 439;; *);; esac + # in that case exit the command with 183 to cancel the build + - | + case `git --no-pager log --pretty="tformat:%s" -1` + in *"skip ci"*) + exit 183;; + *);; + esac Generate documentation from annotated sources with Doxygen diff --git a/docs/user/builds.rst b/docs/user/builds.rst index 688bcd846e3..fe77b9aa72d 100644 --- a/docs/user/builds.rst +++ b/docs/user/builds.rst @@ -68,6 +68,46 @@ The following are the pre-defined jobs executed by Read the Docs: it's possible to run user-defined commands and :doc:`customize the build process `. +When to cancel builds +--------------------- + +There may be situations where you want to cancel a particular running build. +Cancelling running builds will allow your team to speed up review times and also help us reduce server costs and ultimately, +our environmental footprint. + +Consider the following scenarios: + +* the build has an external dependency that hasn't been updated +* there were no changes on the documentation files +* many other use cases that can be solved with custom logic + +For these scenarios, +Read the Docs supports three different mechanisms to cancel a running build: + +:Manually: + + Once a build was triggered, + project administrators can go to the build detail page + and click the button "Cancel build". + +:Automatically: + + When Read the Docs detects a push to a branch that it's currently building the documentation, + it cancels the running build and start a new build using the latest commit from the new push. + +:Programatically: + + You can use user-defined commands on ``build.jobs`` or ``build.commands`` (see :doc:`build-customization`) + to check for a condition and exit it with the code ``183`` if you want to cancel the running build or ``0``, otherwise. + + In this case, Read the Docs will communicate to your Git platform (GitHub/GitLab) that the build succeeded (green tick ✅) + so the pull request is in a mergeable state. + + .. tip:: + + Take a look at :ref:`build-customization:cancel build based on a condition` section for some examples. + + Build resources ---------------