Merge branch 'issue-32560' into 'master'

Documentation improvement for the interruptible keyword

Closes #32560

See merge request gitlab-org/gitlab!17639

doc/ci/yaml/README.md

@@ -117,7 +117,7 @@ The following table lists available parameters for jobs:
 | [`extends`](#extends)                              | Configuration entries that this job is going to inherit from.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
 | [`pages`](#pages)                                  | Upload the result of a job to use with GitLab Pages.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | [`variables`](#variables)                          | Define job variables on a job level.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| [interruptible](#interruptible)                    | Defines if a job can be canceled when made redundant by a newer run                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| [`interruptible`](#interruptible)                  | Defines if a job can be canceled when made redundant by a newer run.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 
 NOTE: **Note:**
 Parameters `types` and `type` are [deprecated](#deprecated-parameters).
@@ -2155,19 +2155,19 @@ staging:
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/23464) in GitLab 12.3.
 
-`interruptible` is used to indicate that a job should be canceled if made redundant by a newer run of the same job. Defaults to `false`.
+`interruptible` is used to indicate that a job should be canceled if made redundant by a newer pipeline run. Defaults to `false`.
 This value will only be used if the [automatic cancellation of redundant pipelines feature](../../user/project/pipelines/settings.md#auto-cancel-pending-pipelines)
 is enabled.
 
 When enabled, a pipeline on the same branch will be canceled when:
 
 - It is made redundant by a newer pipeline run.
-- Either all jobs are set as interruptible, or any uninterruptible jobs are not yet pending.
+- Either all jobs are set as interruptible, or any uninterruptible jobs have not started.
 
 Pending jobs are always considered interruptible.
 
 TIP: **Tip:**
-Set jobs as uninterruptible that should behave atomically and should never be canceled once started.
+Set jobs as interruptible that can be safely canceled once started (for instance, a build job).
 
 Here is a simple example:
 
@@ -2175,23 +2175,33 @@ Here is a simple example:
 stages:
   - stage1
   - stage2
+  - stage3
 
 step-1:
   stage: stage1
   script:
-    - echo "Can be canceled"
+    - echo "Can be canceled."
+  interruptible: true
 
 step-2:
   stage: stage2
   script:
-    - echo "Can not be canceled"
-  interruptible: false
+    - echo "Can not be canceled."
+
+step-3:
+  stage: stage3
+  script:
+    - echo "Because step-2 can not be canceled, this step will never be canceled, even though set as interruptible."
+  interruptible: true
 ```
 
 In the example above, a new pipeline run will cause an existing running pipeline to be:
 
 - Canceled, if only `step-1` is running or pending.
-- Not canceled, once `step-2` becomes pending.
+- Not canceled, once `step-2` starts running.
+
+NOTE: **Note:**
+Once an uninterruptible job is running, the pipeline will never be canceled, regardless of the final job's state.
 
 ### `include`