docs: clarify tasks success criteria for background runnable

Google APIs · copybara-github · commit 07ede94493ac · 2024-08-19T23:44:56.000-07:00
PiperOrigin-RevId: 665192663
diff --git a/google/cloud/batch/v1/task.proto b/google/cloud/batch/v1/task.proto
@@ -304,13 +304,24 @@ message Runnable {
   // provided the index of the runnable will be used for outputs.
   string display_name = 10 [(google.api.field_behavior) = OPTIONAL];
 
-  // Normally, a non-zero exit status causes the Task to fail. This flag allows
-  // execution of other Runnables to continue instead.
+  // Normally, a runnable that returns a non-zero exit status fails and causes
+  // the task to fail. However, you can set this field to `true` to allow the
+  // task to continue executing its other runnables even if this runnable
+  // fails.
   bool ignore_exit_status = 3;
 
-  // This flag allows a Runnable to continue running in the background while the
-  // Task executes subsequent Runnables. This is useful to provide services to
-  // other Runnables (or to provide debugging support tools like SSH servers).
+  // Normally, a runnable that doesn't exit causes its task to fail. However,
+  // you can set this field to `true` to configure a background runnable.
+  // Background runnables are allowed continue running in the background while
+  // the task executes subsequent runnables. For example, background runnables
+  // are useful for providing services to other runnables or providing
+  // debugging-support tools like SSH servers.
+  //
+  // Specifically, background runnables are killed automatically (if they have
+  // not already exited) a short time after all foreground runnables have
+  // completed. Even though this is likely to result in a non-zero exit status
+  // for the background runnable, these automatic kills are not treated as task
+  // failures.
   bool background = 4;
 
   // By default, after a Runnable fails, no further Runnable are executed. This
@@ -339,15 +350,13 @@ message TaskSpec {
   // Required. The sequence of one or more runnables (executable scripts,
   // executable containers, and/or barriers) for each task in this task group to
   // run. Each task runs this list of runnables in order. For a task to succeed,
-  // all of its script and container runnables each must either exit with a zero
-  // status or enable the `ignore_exit_status` subfield and exit with any
-  // status.
+  // all of its script and container runnables each must meet at least one of
+  // the following conditions:
   //
-  // Background runnables are killed automatically (if they have not already
-  // exited) a short time after all foreground runnables have completed. Even
-  // though this is likely to result in a non-zero exit status for the
-  // background runnable, these automatic kills are not treated as Task
-  // failures.
+  // + The runnable exited with a zero status.
+  // + The runnable didn't finish, but you enabled its `background` subfield.
+  // + The runnable exited with a non-zero status, but you enabled its
+  //   `ignore_exit_status` subfield.
   repeated Runnable runnables = 8;
 
   // ComputeResource requirements.
