Updated introductory topics for merge pipelines

doc/ci/merge_request_pipelines/index.md

@@ -7,40 +7,32 @@ last_update: 2019-07-03
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/15310) in GitLab 11.6.
 
-Usually, when you create a new merge request, a pipeline runs with the
-new change and checks if it's qualified to be merged into a target branch. This
-pipeline should contain only necessary jobs for validating the new changes.
-For example, unit tests, lint checks, and [Review Apps](../review_apps/index.md)
-are often used in this cycle.
+In a [basic configuration](../pipelines/pipeline_architectures.md), GitLab runs a pipeline each time
+changes are pushed to a branch. The settings in the [`.gitlab-ci.yml`](../yaml/README.md)
+file, including `rules`, `only`, and `except`, determine which jobs are added to a pipeline.
 
-With pipelines for merge requests, you can design a specific pipeline structure
-for when you are running a pipeline in a merge request. This
-could be either adding or removing steps in the pipeline, to make sure that
-your pipelines are as efficient as possible.
+If you want the pipeline to run jobs **only** when merge requests are created or updated,
+you can use *pipelines for merge requests*.
 
-## Requirements and limitations
+In the UI, these pipelines are labeled as `detached`.
 
-Pipelines for merge requests have the following requirements and limitations:
+![Merge request page](img/merge_request.png)
+
+A few notes:
 
-- As of GitLab 11.10, pipelines for merge requests require GitLab Runner 11.9
-  or higher due to the
-  [recent refspecs changes](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/25504).
 - Pipelines for merge requests are incompatible with
   [CI/CD for external repositories](../ci_cd_for_external_repos/index.md).
+- [Since GitLab 11.10](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/25504), pipelines for merge requests require GitLab Runner 11.9.
 
 ## Configuring pipelines for merge requests
 
 To configure pipelines for merge requests, add the `only: [merge_requests]` parameter to
-the jobs that you want to run only for merge requests.
-
-Then, when developers create or update merge requests, a pipeline runs
-every time a commit is pushed to GitLab.
+your `.gitlab-ci.yml` file.
 
-NOTE: **Note**:
-If you use this feature with [merge when pipeline succeeds](../../user/project/merge_requests/merge_when_pipeline_succeeds.md),
-pipelines for merge requests take precedence over the other regular pipelines.
+In this example, the pipeline contains a `test` job that is configured to run on merge requests.
 
-For example, consider the following [`.gitlab-ci.yml`](../yaml/README.md):
+The `build` and `deploy` jobs don't have the `only: - merge_requests` parameter,
+so they will not run on merge requests.
 
 ```yaml
 build:
@@ -62,19 +54,14 @@ deploy:
   - master
 ```
 
-After the merge request is updated with new commits:
+Whenever a merge request is updated with new commits:
 
 - GitLab detects that changes have occurred and creates a new pipeline for the merge request.
 - The pipeline fetches the latest code from the source branch and run tests against it.
 
-In the above example, the pipeline contains only a `test` job.
-Since the `build` and `deploy` jobs don't have the `only: [merge_requests]` parameter,
-they will not run in the merge request.
-
-Pipelines tagged with the **detached** badge indicate that they were triggered
-when a merge request was created or updated. For example:
-
-![Merge request page](img/merge_request.png)
+NOTE: **Note**:
+If you use this feature with [merge when pipeline succeeds](../../user/project/merge_requests/merge_when_pipeline_succeeds.md),
+pipelines for merge requests take precedence over the other regular pipelines.
 
 ## Pipelines for Merged Results **(PREMIUM)**
 
@@ -129,10 +116,8 @@ Therefore:
 - Since `C` specifies that it should only run for merge requests, it will not run for any pipeline
   except a merge request pipeline.
 
-As you can see, this will help you avoid a lot of boilerplate where you'd need
-to add that `only:` rule to all of your jobs in order to make them always run. You
-can use this for scenarios like having only pipelines with merge requests get a
-Review App set up, helping to save resources.
+This helps you avoid having to add the `only:` rule to all of your jobs
+in order to make them always run. You can use this format to set up a Review App, helping to save resources.
 
 ## Excluding certain branches
 

doc/ci/merge_request_pipelines/pipelines_for_merged_results/index.md

@@ -7,31 +7,32 @@ last_update: 2019-07-03
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/7380) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.10.
 
-It's possible for your source and target branches to diverge, which can result
-in the scenario that source branch's pipeline was green, the target's pipeline was green,
-but the combined output fails.
-
-By having your merge request pipeline automatically
-create a new ref that contains the merge result of the source and target branch
-(then running a pipeline on that ref), we can better test that the combined result
-is also valid.
-
-GitLab can run pipelines for merge requests
-on this merged result. That is, where the source and target branches are combined into a
-new ref and a pipeline for this ref validates the result prior to merging.
-
-![Merge request pipeline as the head pipeline](img/merged_result_pipeline_v12_3.png)
-
-There are some cases where creating a combined ref is not possible or not wanted.
-For example, a source branch that has conflicts with the target branch
-or a merge request that is still in WIP status. In this case,
-GitLab doesn't create a merge commit and the pipeline runs on source branch, instead,
-which is a default behavior of [Pipelines for merge requests](../index.md)
- i.e. `detached` label is shown to the pipelines.
-
-The detached state serves to warn you that you are working in a situation
-subjected to merge problems, and helps to highlight that you should
-get out of WIP status or resolve merge conflicts as soon as possible.
+When you submit a merge request, you are requesting to merge changes from a
+source branch into a target branch. By default, the CI pipeline runs jobs
+against the source branch.
+
+With *pipelines for merged results*, the pipeline runs as if the changes from
+the source branch have already been merged into the target branch.
+
+If the pipeline fails due to a problem in the target branch, you can wait until the
+target is fixed and re-run the pipeline.
+This new pipeline will run as if the source is merged with the updated target, and you
+will not need to rebase.
+
+The pipeline does not automatically run when the target branch changes. Only changes
+to the source branch trigger a new pipeline. If a long time has passed since the last successful
+pipeline, you may want to re-run it before merge, to ensure that the source changes
+can still be successfully merged into the target.
+
+When the merge request can't be merged, the pipeline runs against the source branch only. For example, when:
+
+- The target branch has changes that conflict with the changes in the source branch.
+- The merge request is a
+  [work in progress](../../../user/project/merge_requests/work_in_progress_merge_requests.md).
+
+In these cases, the pipeline runs as a [pipeline for merge requests](../index.md)
+and is labeled as `detached`. If these cases no longer exist, new pipelines will
+again run against the merged results.
 
 ## Requirements and limitations
 

doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md

@@ -8,31 +8,57 @@ last_update: 2019-07-03
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/9186) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.0.
 > - [Squash and merge](../../../../user/project/merge_requests/squash_and_merge.md) support [introduced](https://gitlab.com/gitlab-org/gitlab/issues/13001) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.6.
 
-[Pipelines for merged results](../index.md#pipelines-for-merged-results-premium) introduces
-running a build on the result of the merged code prior to merging, as a way to keep master green.
+When [pipelines for merged results](../index.md#pipelines-for-merged-results-premium) are
+enabled, the pipeline jobs run as if the changes from your source branch have already
+been merged into the target branch.
 
-There's a scenario, however, for teams with a high number of changes in the target branch (typically master) where in many or even all cases,
-by the time the merged code is validated another commit has made it to master, invalidating the merged result.
-You'd need some kind of queuing, cancellation or retry mechanism for these scenarios
-in order to ensure an orderly flow of changes into the target branch.
+However, the target branch may be changing rapidly. When you're ready to merge,
+if you haven't run the pipeline in a while, the target branch may have already changed.
+Merging now could introduce breaking changes.
 
-Each MR that joins a merge train joins as the last item in the train,
-just as it works in the current state. However, instead of queuing and waiting,
-each item takes the completed state of the previous (pending) merge ref, adds its own changes,
-and starts the pipeline immediately in parallel under the assumption that everything is going to pass.
+*Merge trains* can prevent this from happening. A merge train is a queued list of merge
+requests, each waiting to be merged into the target branch.
 
-This means that if all the pipelines in the train merge successfully, no pipeline time is wasted either queuing or retrying.
-If the button is subsequently pressed in a different MR, instead of creating a new pipeline for the target branch,
-it creates a new pipeline targeting the merge result of the previous MR plus the target branch.
-Pipelines invalidated through failures are immediately canceled and requeued.
+Each merge request on the train runs the merged results pipeline immediately before its
+changes are merged into the target branch. If the pipeline fails, the breaking changes are
+not merged, and the target branch is unaffected.
+
+Many merge requests can be added to the train. Each is trying to merge into the target branch.
+Each request runs its own merged results pipeline, which includes the changes from
+all of the other merge requests in *front* of it on the train. All the pipelines run
+in parallel, to save time.
+
+If the pipeline for the merge request at the front of the train completes successfully,
+the changes are merged into the target branch, and the other pipelines will continue to
+run.
+
+If one of the pipelines fails, it is removed from the train, and all pipelines behind
+it restart, but without the changes that were removed.
+
+Three merge requests (`A`, `B` and `C`) are added to a merge train in order, which
+creates three merged results pipelines that run in parallel:
+
+1. The first pipeline runs on the changes from `A` combined with the target branch.
+1. The second pipeline runs on the changes from `A` and `B` combined with the target branch.
+1. The third pipeline runs on the changes from `A`, `B`, and `C` combined with the target branch.
+
+If the pipeline for `B` fails, it is removed from the train. The pipeline for
+`C` restarts with the `A` and `C` changes, but without the `B` changes.
+
+If `A` then completes successfully, it merges into the target branch, and `C` continues
+to run. If more merge requests are added to the train, they will now include the `A`
+changes that are included in the target branch, and the `C` changes that are from
+the merge request already in the train.
+
+Learn more about
+[how merge trains keep your master green](https://about.gitlab.com/blog/2020/01/30/all-aboard-merge-trains/).
 
 ## Requirements and limitations
 
 Merge trains have the following requirements and limitations:
 
-- GitLab 12.0 and later requires [Redis](https://redis.io/) 3.2 or higher to run Merge Trains.
-- This feature requires that
-  [pipelines for merged results](../index.md#pipelines-for-merged-results-premium) are
+- GitLab 12.0 and later requires [Redis](https://redis.io/) 3.2 or higher.
+- [Pipelines for merged results](../index.md#pipelines-for-merged-results-premium) must be
   **configured properly**.
 - Each merge train can run a maximum of **twenty** pipelines in parallel.
   If more than twenty merge requests are added to the merge train, the merge requests
@@ -70,7 +96,7 @@ current position will be displayed under the pipeline widget:
 ## Start/Add to merge train when pipeline succeeds
 
 You can add a merge request to a merge train only when the latest pipeline in the
-merge request finished. While the pipeline is running or pending, you cannot add
+merge request is finished. While the pipeline is running or pending, you cannot add
 the merge request to a train because the current change of the merge request may
 be broken thus it could affect the following merge requests.