From 3bb637c0261f8c08d4346175bb8b1024719a1f11 Mon Sep 17 00:00:00 2001 From: Anton Gilgur <4970083+agilgur5@users.noreply.github.com> Date: Mon, 17 Jun 2024 01:10:08 -0400 Subject: [PATCH] docs: full copy-edit of enhanced `depends` page (#13110) Signed-off-by: Anton Gilgur (cherry picked from commit 669d4a4e986b359dde3cd07e5616be8f713fe23d) --- docs/enhanced-depends-logic.md | 51 +++++++++++++--------------------- 1 file changed, 20 insertions(+), 31 deletions(-) diff --git a/docs/enhanced-depends-logic.md b/docs/enhanced-depends-logic.md index 64328d0005c3..f5eaa11df6b8 100644 --- a/docs/enhanced-depends-logic.md +++ b/docs/enhanced-depends-logic.md @@ -2,35 +2,26 @@ > v2.9 and after -## Introduction - -Previous to version 2.8, the only way to specify dependencies in DAG templates was to use the `dependencies` field and -specify a list of other tasks the current task depends on. This syntax was limiting because it does not allow the user to -specify which _result_ of the task to depend on. For example, a task may only be relevant to run if the dependent task -succeeded (or failed, etc.). +Enhanced `depends` improves on [the `dependencies` field](walk-through/dag.md) by specifying which _result_ of a task to depend on. +For example, to only run a task if its dependent task succeeded. ## Depends -To remedy this, there exists a new field called `depends`, which allows users to specify dependent tasks, their statuses, -as well as any complex boolean logic. The field is a `string` field and the syntax is expression-like with operands having -form `.`. Examples include `task-1.Succeeded`, `task-2.Failed`, `task-3.Daemoned`. The full list of -available task results is as follows: - -| Task Result | Description | Meaning | -|:------------:|----------------|---------| -| `.Succeeded` | Task Succeeded | Task finished with no error | -| `.Failed` | Task Failed | Task exited with a non-0 exit code | -| `.Errored` | Task Errored | Task had an error other than a non-0 exit code | -| `.Skipped` | Task Skipped | Task was skipped | -| `.Omitted` | Task Omitted | Task was omitted | -| `.Daemoned` | Task is Daemoned and is not Pending | | +You can use the `depends` field to specify dependent tasks, their results, and boolean logic between them. -A tasks is considered `Skipped` if its `when` condition evaluates to false. On the other hand, if a task doesn't run -because its `depends` evaluated to false it is `Omitted`. +You use operands of the form `.`, such as `task-1.Succeeded`, `task-2.Failed`, `task-3.Daemoned`. +Available task results are: -For convenience, an omitted task result is equivalent to `(task.Succeeded || task.Skipped || task.Daemoned)`. +| Task Result | Description | +|:------------:|-------------| +| `.Succeeded` | Task finished with no error | +| `.Failed` | Task exited with a non-0 exit code | +| `.Errored` | Task had an error other than a non-0 exit code | +| `.Skipped` | Task's [`when`](walk-through/conditionals.md) condition evaluated to `false` | +| `.Omitted` | Task's `depends` condition evaluated to `false` | +| `.Daemoned` | Task is [daemoned](walk-through/daemon-containers.md) and is not `Pending` | -For example: +For compatibility with `dependencies`, an unspecified result is equivalent to `(task.Succeeded || task.Skipped || task.Daemoned)`. For example: ```yaml depends: "task || task-2.Failed" @@ -42,20 +33,19 @@ is equivalent to: depends: (task.Succeeded || task.Skipped || task.Daemoned) || task-2.Failed ``` -Full boolean logic is also available. Operators include: +You can use boolean logic with the operators: * `&&` * `||` * `!` - Example: +Example: ```yaml depends: "(task-2.Succeeded || task-2.Skipped) && !task-3.Failed" ``` -In the case that you're depending on a task that uses `withItems`, you can depend on -whether any of the item tasks are successful or all have failed using `.AnySucceeded` and `.AllFailed`, for example: +If you depend on a task that uses `withItems`, you can use `.AnySucceeded` and `.AllFailed`. For example: ```yaml depends: "task-1.AnySucceeded || task-2.AllFailed" @@ -63,9 +53,9 @@ depends: "task-1.AnySucceeded || task-2.AllFailed" ## Compatibility with `dependencies` and `dag.task.continueOn` -This feature is fully compatible with `dependencies` and conversion is easy. +You cannot use both `dependencies` and `depends` in the same task group. -To convert simply join your `dependencies` with `&&`: +To convert from `dependencies` to `depends`, join your array into a string with `&&`. For example: ```yaml dependencies: ["A", "B", "C"] @@ -77,5 +67,4 @@ is equivalent to: depends: "A && B && C" ``` -Because of the added control found in `depends`, the `dag.task.continueOn` is not available when using it. Furthermore, -it is not possible to use both `dependencies` and `depends` in the same task group. +`dag.task.continueOn` is not available when using `depends`; instead you can specify `.Failed`.