Merge branch 'docs-for-merge-train-parallel-pipelines' into 'master'

Documentations for parallel execution strategy for Merge Trains

Closes #63369

See merge request gitlab-org/gitlab-ce!30661

3 files changed, 27 insertions, 21 deletions

diff --git a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/index.md b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/index.md
index a13857bee25..f63b17a9e5a 100644
--- a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/index.md
+++ b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/index.md
@@ -6,7 +6,6 @@ last_update: 2019-07-03
 # Pipelines for Merged Results **(PREMIUM)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/7380) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.10.
-> This feature is disabled by default until we resolve issues with [contention handling](https://gitlab.com/gitlab-org/gitlab-ee/issues/11222), but [can be enabled manually](#enabling-pipelines-for-merged-results).
 
 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,
@@ -25,8 +24,10 @@ new ref and a pipeline for this ref validates the result prior to merging.
 
 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, the merge request pipeline falls back to a "detached" state
-and runs on the source branch ref as if it was a regular pipeline.
+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
@@ -42,7 +43,7 @@ Pipelines for merged results require:
 In addition, pipelines for merged results have the following limitations:
 
 - Forking/cross-repo workflows are not currently supported. To follow progress,
-  see [#9713](https://gitlab.com/gitlab-org/gitlab-ee/issues/9713).
+  see [#11934](https://gitlab.com/gitlab-org/gitlab-ee/issues/11934).
 - This feature is not available for
   [fast forward merges](../../../user/project/merge_requests/fast_forward_merge.md) yet.
   To follow progress, see [#58226](https://gitlab.com/gitlab-org/gitlab-ce/issues/58226).
diff --git a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/img/merge_train_position_v12_0.png b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/img/merge_train_position_v12_0.png
new file mode 100644
index 00000000000..70916bc0e00
--- /dev/null
+++ b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/img/merge_train_position_v12_0.png
diff --git a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md
index 57358434c02..44cbcde264c 100644
--- a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md
+++ b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md
@@ -6,7 +6,6 @@ last_update: 2019-07-03
 # Merge Trains **(PREMIUM)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/9186) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.0.
-> This feature is disabled by default, but [can be enabled manually](#enabling-merge-trains).
 
 [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.
@@ -33,35 +32,40 @@ Merge trains have the following requirements and limitations:
 - This feature requires that
   [pipelines for merged results](../index.md#pipelines-for-merged-results-premium) are
   **configured properly**.
-- Each merge train can generate a merge ref and run a pipeline **one at a time**.
-  We plan to make the pipelines for merged results
-  [run in parallel](https://gitlab.com/gitlab-org/gitlab-ee/issues/11222) in a
-  future release.
+- Each merge train can run a maximum of **four** pipelines in parallel.
+  If more than four merge requests are added to the merge train, the merge requests
+  will be queued until a slot in the merge train is free. There is no limit to the
+  number of merge requests that can be queued.
+- This feature does not support [squash and merge](../../../../user/project/merge_requests/squash_and_merge.md).
 
-## Enabling Merge Trains
-
-To enable merge trains at the project level:
-
-1. Visit your project's **Settings > General** and expand **Merge requests**.
-1. Check **Allow merge trains**.
-1. Click **Save changes** button.
-
-![Merge request pipeline config](img/merge_train_config_v12_0.png)
+<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
+Watch this video for a demonstration on [how parallel execution
+of Merge Trains can prevent commits from breaking the default
+branch](https://www.youtube.com/watch?v=D4qCqXgZkHQ).
 
 ## How to add a merge request to a merge train
 
 To add a merge request to a merge train:
 
-1. Click "Start/Add merge train" button in a merge request
+1. Visit a merge request.
+1. Click the **Start/Add to merge train** button.
 
 ![Start merge train](img/merge_train_start_v12_0.png)
 
 ## How to remove a merge request from a merge train
 
-1. Click "Remove from merge train" button in the merge request widget.
+1. Visit a merge request.
+1. Click the **Remove from merge train** button.
 
 ![Cancel merge train](img/merge_train_cancel_v12_0.png)
 
+## How to view a merge request's current position on the merge train
+
+After a merge request has been added to the merge train, the merge request's
+current position will be displayed under the pipeline widget:
+
+![Merge train position indicator](img/merge_train_position_v12_0.png)
+
 ## 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
@@ -70,7 +74,8 @@ 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.
 
 In this case, you can schedule to add the merge request to a merge train **when the latest
-pipeline succeeds**. You can see the following button instead of the regular "Start/Add merge train"
+pipeline succeeds** (This pipeline is [Pipelines for merged results](../index.md), not Pipelines for merge train).
+You can see the following button instead of the regular **Start/Add to merge train**
 button while the latest pipeline is running.
 
 ![Add to merge train when pipeline succeeds](img/merge_train_start_when_pipeline_succeeds_v12_0.png)