Merge branch 'docs-mwps-clarification' into 'master'

Update docs for mwps

See merge request gitlab-org/gitlab!36777

doc/user/project/merge_requests/merge_when_pipeline_succeeds.md

 ---
+stage: Create
+group: Source Code
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
 type: reference, concepts
 ---
 
 # Merge when pipeline succeeds
 
-When reviewing a merge request that looks ready to merge but still has one or
-more CI jobs running, you can set it to be merged automatically when the
-jobs pipeline succeeds. This way, you don't have to wait for the jobs to
+When reviewing a merge request that looks ready to merge but still has a
+pipeline running, you can set it to merge automatically when the
+pipeline succeeds. This way, you don't have to wait for the pipeline to
 finish and remember to merge the request manually.
 
 ![Enable](img/merge_when_pipeline_succeeds_enable.png)
 
 ## How it works
 
-When you hit the "Merge When Pipeline Succeeds" button, the status of the merge
-request will be updated to represent the impending merge. If you cannot wait
-for the pipeline to succeed and want to merge immediately, this option is
-available in the dropdown menu on the right of the main button.
+When you click "Merge When Pipeline Succeeds", the status of the merge
+request is updated to show the impending merge. If you can't wait
+for the pipeline to succeed, you can choose **Merge immediately**
+in the dropdown menu on the right of the main button.
 
-Both team developers and the author of the merge request have the option to
-cancel the automatic merge if they find a reason why it shouldn't be merged
-after all.
+The author of the merge request and project members with developer permissions can
+cancel the automatic merge at any time before the pipeline finishes.
 
 ![Status](img/merge_when_pipeline_succeeds_status.png)
 
-When the pipeline succeeds, the merge request will automatically be merged.
+When the pipeline succeeds, the merge request is automatically merged.
 When the pipeline fails, the author gets a chance to retry any failed jobs,
 or to push new commits to fix the failure.
 
 When the jobs are retried and succeed on the second try, the merge request
-will automatically be merged after all. When the merge request is updated with
-new commits, the automatic merge is automatically canceled to allow the new
+is automatically merged. When the merge request is updated with
+new commits, the automatic merge is canceled to allow the new
 changes to be reviewed.
 
 ## Only allow merge requests to be merged if the pipeline succeeds
@@ -42,7 +44,7 @@ or if there are threads to be resolved. This works for both:
 - Pipelines run from an [external CI integration](../integrations/overview.md#integrations-listing)
 
 As a result, [disabling GitLab CI/CD pipelines](../../../ci/enable_or_disable_ci.md)
-will not disable this feature, as it will still be possible to use pipelines from external
+does not disable this feature, as it is possible to use pipelines from external
 CI providers with this feature. To enable it, you must:
 
 1. Navigate to your project's **Settings > General** page.
@@ -50,14 +52,40 @@ CI providers with this feature. To enable it, you must:
 1. In the **Merge checks** subsection, select the **Pipelines must succeed** checkbox.
 1. Press **Save** for the changes to take effect.
 
-NOTE: **Note:** This setting also prevents merge requests from being merged if there is no pipeline.
+This setting also prevents merge requests from being merged if there is no pipeline.
 
-![Pipelines must succeed settings](img/merge_when_pipeline_succeeds_only_if_succeeds_settings.png)
+### Limitations
+
+When this setting is enabled, a merge request is prevented from being merged if there
+is no pipeline. This may conflict with some use cases where [`only/except`](../../../ci/yaml/README.md#onlyexcept-advanced)
+or [`rules`](../../../ci/yaml/README.md#rules) are used and they don't generate any pipelines.
+
+You should ensure that [there is always a pipeline](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/54226)
+and that it's successful.
+
+If both a branch pipeline and a merge request pipeline are triggered for a single
+merge request, only the success or failure of the *merge request pipeline* is checked.
+If the merge request pipeline is configured with fewer jobs than the branch pipeline,
+it could allow code that fails tests to be merged:
+
+```yaml
+branch-pipeline-job:
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "push"'
+  script:
+    - echo "Code testing scripts here, for example."
 
-From now on, every time the pipeline fails you will not be able to merge the
-merge request from the UI, until you make all relevant jobs pass.
+merge-request-pipeline-job:
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
+  script:
+    - echo "No tests run, but this pipeline always succeeds and enables merge."
+    - echo true
+```
 
-![Only allow merge if pipeline succeeds message](img/merge_when_pipeline_succeeds_only_if_succeeds_msg.png)
+You should avoid configuration like this, and only use branch (`push`) pipelines
+or merge request pipelines, when possible. See [`rules` documentation](../../../ci/yaml/README.md#differences-between-rules-and-onlyexcept)
+for details on avoiding two pipelines for a single merge request.
 
 ### Skipped pipelines
 
@@ -72,20 +100,10 @@ merge requests from being merged. To change this behavior:
 1. In the **Merge checks** subsection, select the **Skipped pipelines are considered successful** checkbox.
 1. Press **Save** for the changes to take effect.
 
-### Limitations
-
-When this setting is enabled, a merge request is prevented from being merged if there is no pipeline. This may conflict with some use cases where [`only/except`](../../../ci/yaml/README.md#onlyexcept-advanced) rules are used and they don't generate any pipelines.
-
-Users that expect to be able to merge a merge request in this scenario should ensure that [there is always a pipeline](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/54226) and that it's successful.
+## From the command line
 
-For example, to that on merge requests there is always a passing job even though `only/except` rules may not generate any other jobs:
-
-```yaml
-enable_merge:
-  only: [merge_requests]
-  script:
-    - echo true
-```
+You can use [Push Options](../push_options.md) to enable merge when pipeline succeeds
+for a merge request when pushing from the command line.
 
 <!-- ## Troubleshooting
 
@@ -98,8 +116,3 @@ questions that you know someone might ask.
 Each scenario can be a third-level heading, e.g. `### Getting error message X`.
 If you have none to add when creating a doc, leave this section in place
 but commented out to help encourage others to add to it in the future. -->
-
-## Use it from the command line
-
-You can use [Push Options](../push_options.md) to trigger this feature when
-pushing.