From 4303d17307084081b15f05207d76a97d4d060eb3 Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Tue, 8 Nov 2022 18:24:02 +0100 Subject: [PATCH 1/6] Docs: refactor "skipping a build" section - Move the explanation about the "Cancelling builds" feature to the "Builds" page - Keep the examples (How-To) for "Cancel a build" into the "Build customization" page --- docs/user/build-customization.rst | 30 ++++++++--------------- docs/user/builds.rst | 40 +++++++++++++++++++++++++++++++ 2 files changed, 50 insertions(+), 20 deletions(-) diff --git a/docs/user/build-customization.rst b/docs/user/build-customization.rst index aee84e1ebc2..9fe457c73e4 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 ``439``, +Read the Docs will cancel the build immediately. +We can use this approach to cancel builds we don't want to complete based on a condition. -* 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,7 +124,7 @@ 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 ! # @@ -143,7 +133,7 @@ Here is an example that skip build from pull requests when there are no changes - if [ $READTHEDOCS_VERSION_TYPE = "external" ]; then ! git diff --quiet origin/main -- docs/ && exit 439; 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,7 +146,7 @@ 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 + # in that case exit the command with 439 to cancel the build - case `git --no-pager log --pretty="tformat:%s" -1` in *"skip ci"*) exit 439;; *);; esac diff --git a/docs/user/builds.rst b/docs/user/builds.rst index 688bcd846e3..26889346173 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 `. +Cancelling 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 depends on an external situation that's not met yet +* there were no changes on the documentation files +* the user wants it for any particular reason + +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 ``439`` 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 --------------- From f417651450e42a384220f9ebe4009c74dc906920 Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Wed, 9 Nov 2022 09:59:04 +0100 Subject: [PATCH 2/6] Docs: use 183 instead of 439 exit code > This error code isn't a valid exit > code (tldp.org/LDP/abs/html/exitcodes.html), we shouldn't document a code above > 255 otherwise users will get confused. From Eric's review. --- docs/user/build-customization.rst | 10 +++++----- docs/user/builds.rst | 2 +- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/user/build-customization.rst b/docs/user/build-customization.rst index 9fe457c73e4..0f8eacc9ab7 100644 --- a/docs/user/build-customization.rst +++ b/docs/user/build-customization.rst @@ -108,7 +108,7 @@ To avoid this, it's possible to unshallow the clone done by Read the Docs: Cancel build based on a condition ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -When a command exits with code ``439``, +When a command exits with code ``183``, Read the Docs will cancel the build immediately. We can use this approach to cancel builds we don't want to complete based on a condition. @@ -128,9 +128,9 @@ Here is an example that cancels builds from pull requests when there are no chan # `--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 cancel a build if the commit message contains ``skip ci`` on it: @@ -146,8 +146,8 @@ This other example shows how to cancel a build if the commit message contains `` jobs: post_checkout: # Use `git log` to check if the latest commit contains "skip ci", - # in that case exit the command with 439 to cancel 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 26889346173..d8f3f975816 100644 --- a/docs/user/builds.rst +++ b/docs/user/builds.rst @@ -98,7 +98,7 @@ Read the Docs supports three different mechanisms to cancel a running build: :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 ``439`` if you want to cancel the running build or ``0``, otherwise. + 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. From 7cb6b0727d76fab73c30bc3a1aa7b91fe914e36d Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Wed, 9 Nov 2022 10:05:09 +0100 Subject: [PATCH 3/6] Apply suggestions from code review Co-authored-by: Eric Holscher <25510+ericholscher@users.noreply.github.com> --- docs/user/build-customization.rst | 2 +- docs/user/builds.rst | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/user/build-customization.rst b/docs/user/build-customization.rst index 0f8eacc9ab7..4c6c1491220 100644 --- a/docs/user/build-customization.rst +++ b/docs/user/build-customization.rst @@ -110,7 +110,7 @@ Cancel build based on a condition When a command exits with code ``183``, Read the Docs will cancel the build immediately. -We can use this approach to cancel builds we don't want to complete based on a condition. +You can use this approach to cancel builds that you don't want to complete based on some conditional logic. 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: diff --git a/docs/user/builds.rst b/docs/user/builds.rst index d8f3f975816..74385ad457a 100644 --- a/docs/user/builds.rst +++ b/docs/user/builds.rst @@ -68,7 +68,7 @@ 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 `. -Cancelling builds +When to cancel builds ----------------- There may be situations where you want to cancel a particular running build. @@ -77,7 +77,7 @@ our environmental footprint. Consider the following scenarios: -* the build depends on an external situation that's not met yet +* the build has an external dependency that hasn't been updated * there were no changes on the documentation files * the user wants it for any particular reason From 8ccd55cf3370e772e8def502fe794386e887daf4 Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Wed, 9 Nov 2022 10:43:35 +0100 Subject: [PATCH 4/6] Minor fix underline --- docs/user/builds.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user/builds.rst b/docs/user/builds.rst index 74385ad457a..708c092b626 100644 --- a/docs/user/builds.rst +++ b/docs/user/builds.rst @@ -69,7 +69,7 @@ The following are the pre-defined jobs executed by Read the Docs: 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, From 1d4ae249e740e4ee7492f6c54cdb83e23d093f83 Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Wed, 9 Nov 2022 13:21:11 +0100 Subject: [PATCH 5/6] Use multi-line bash examples They are easier to read --- docs/user/build-customization.rst | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/docs/user/build-customization.rst b/docs/user/build-customization.rst index 4c6c1491220..49681a0959a 100644 --- a/docs/user/build-customization.rst +++ b/docs/user/build-customization.rst @@ -130,7 +130,11 @@ Here is an example that cancels builds from pull requests when there are no chan # # 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 183; fi + - | + if [ $READTHEDOCS_VERSION_TYPE = "external" ]; + then + ! git diff --quiet origin/main -- docs/ && exit 183; + fi This other example shows how to cancel a build if the commit message contains ``skip ci`` on it: @@ -147,7 +151,12 @@ This other example shows how to cancel a build if the commit message contains `` post_checkout: # Use `git log` to check if the latest commit contains "skip ci", # 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 + - | + case `git --no-pager log --pretty="tformat:%s" -1` + in *"skip ci"*) + exit 183;; + *);; + esac Generate documentation from annotated sources with Doxygen From 3222ef5489bbb9c07672a4989d210247c87d6458 Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Thu, 10 Nov 2022 09:21:18 +0100 Subject: [PATCH 6/6] Update docs/user/builds.rst Co-authored-by: Eric Holscher <25510+ericholscher@users.noreply.github.com> --- docs/user/builds.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user/builds.rst b/docs/user/builds.rst index 708c092b626..fe77b9aa72d 100644 --- a/docs/user/builds.rst +++ b/docs/user/builds.rst @@ -79,7 +79,7 @@ Consider the following scenarios: * the build has an external dependency that hasn't been updated * there were no changes on the documentation files -* the user wants it for any particular reason +* 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: