Merge branch 'selhorn-mrpipelines1' into 'master'

Added Enable instructions to pipelines for MR docs

See merge request gitlab-org/gitlab!29284

doc/api/merge_requests.md

@@ -904,7 +904,7 @@ The new pipeline can be:
 
 - A detached merge request pipeline.
 - A [pipeline for merged results](../ci/merge_request_pipelines/pipelines_for_merged_results/index.md)
-  if the [project setting is enabled](../ci/merge_request_pipelines/pipelines_for_merged_results/index.md#enabling-pipelines-for-merged-results).
+  if the [project setting is enabled](../ci/merge_request_pipelines/pipelines_for_merged_results/index.md#enable-pipelines-for-merged-results).
 
 ```plaintext
 POST /projects/:id/merge_requests/:merge_request_iid/pipelines

doc/ci/merge_request_pipelines/index.md

@@ -7,9 +7,8 @@ last_update: 2019-07-03
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/15310) in GitLab 11.6.
 
-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.
+In a [basic configuration](../pipelines/pipeline_architectures.md#basic-pipelines), GitLab runs a pipeline each time
+changes are pushed to a branch.
 
 If you want the pipeline to run jobs **only** when merge requests are created or updated,
 you can use *pipelines for merge requests*.
@@ -28,7 +27,7 @@ A few notes:
 
 ## Configuring pipelines for merge requests
 
-To configure pipelines for merge requests, configure your CI yaml file.
+To configure pipelines for merge requests, configure your [CI/CD configuration file](../yaml/README.md).
 There are a few different ways to do this.
 
 ### Enable pipelines for merge requests for all jobs

doc/ci/merge_request_pipelines/pipelines_for_merged_results/index.md

@@ -36,31 +36,41 @@ again run against the merged results.
 
 ## Requirements and limitations
 
-Pipelines for merged results require a [GitLab Runner][runner] 11.9 or newer.
-
-[runner]: https://gitlab.com/gitlab-org/gitlab-runner
-
-In addition, pipelines for merged results have the following limitations:
+Pipelines for merged results have the following requirements and limitations:
 
+- Pipelines for merged results require [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-runner) 11.9 or newer.
 - Forking/cross-repo workflows are not currently supported. To follow progress,
   see [#11934](https://gitlab.com/gitlab-org/gitlab/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/-/issues/26996).
 
-## Enabling Pipelines for Merged Results
+## Enable pipelines for merged results
 
-To enable pipelines on merged results at the project level:
+To enable pipelines for merged results for your project:
 
+1. [Configure your CI/CD configuration file](../index.md#configuring-pipelines-for-merge-requests)
+   so that the pipeline or individual jobs run for merge requests.
 1. Visit your project's **Settings > General** and expand **Merge requests**.
 1. Check **Merge pipelines will try to validate the post-merge result prior to merging**.
-1. Click **Save changes** button.
+1. Click **Save changes**.
+
+CAUTION: **Caution:**
+If you select the check box but don't configure your CI/CD to use
+pipelines for merge requests, your merge requests may become stuck in an
+unresolved state or your pipelines may be dropped.
+
+## Using Merge Trains
 
-![Merge request pipeline config](img/merge_request_pipeline_config.png)
+When you enable [Pipelines for merged results](#pipelines-for-merged-results-premium),
+GitLab [automatically displays](merge_trains/index.md#add-a-merge-request-to-a-merge-train)
+a **Start/Add Merge Train button**.
 
-CAUTION: **Warning:**
-Make sure your `gitlab-ci.yml` file is [configured properly for pipelines for merge requests](../index.md#configuring-pipelines-for-merge-requests),
-otherwise pipelines for merged results won't run and your merge requests will be stuck in an unresolved state.
+Generally, this is a safer option than merging merge requests immediately, because your
+merge request will be evaluated with an expected post-merge result before the actual
+merge happens.
+
+For more information, read the [documentation on Merge Trains](merge_trains/index.md).
 
 ## Automatic pipeline cancelation
 
@@ -118,15 +128,3 @@ which indicates that the checkout-SHA is not found in the merge ref.
 
 This behavior was improved at GitLab 12.4 by introducing [Persistent pipeline refs](../../pipelines/index.md#troubleshooting-fatal-reference-is-not-a-tree).
 You should be able to create pipelines at any timings without concerning the error.
-
-## Using Merge Trains **(PREMIUM)**
-
-By enabling [Pipelines for merged results](#pipelines-for-merged-results-premium),
-GitLab will [automatically display](merge_trains/index.md#how-to-add-a-merge-request-to-a-merge-train)
-a **Start/Add Merge Train button** as the most recommended merge strategy.
-
-Generally, this is a safer option than merging merge requests immediately as your
-merge request will be evaluated with an expected post-merge result before the actual
-merge happens.
-
-For more information, read the [documentation on Merge Trains](merge_trains/index.md).

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

@@ -19,21 +19,18 @@ Merging now could introduce breaking changes.
 *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.
 
-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 merge 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.
 
-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 a merge request fails, the breaking changes are not merged, and the target
+branch is unaffected. The merge request is removed from the train, and all pipelines behind it restart.
 
 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
+the changes are merged into the target branch, and the other pipelines 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.
+## Merge train example
 
 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:
@@ -50,85 +47,99 @@ to run. If more merge requests are added to the train, they will now include the
 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
+Read more about
 [how merge trains keep your master green](https://about.gitlab.com/blog/2020/01/30/all-aboard-merge-trains/).
 
+<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).
+
 ## Requirements and limitations
 
 Merge trains have the following requirements and limitations:
 
+- Merge trains require [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-runner) 11.9 or newer.
 - 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
   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.
 
-<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).
+## Enable merge trains
 
-## How to add a merge request to a merge train
+To enable merge trains for your project:
 
-To add a merge request to a merge train:
+1. If you are on a self-managed GitLab instance, ensure the [feature flag](#merge-trains-feature-flag-premium-only) is set correctly.
+1. [Configure your CI/CD configuration file](../../index.md#configuring-pipelines-for-merge-requests)
+   so that the pipeline or individual jobs run for merge requests.
+1. Visit your project's **Settings > General** and expand **Merge requests**.
+1. Check **Merge pipelines will try to validate the post-merge result prior to merging**.
+1. Click **Save changes**.
+
+CAUTION: **Caution:**
+If you select the check box but don't configure your CI/CD to use
+pipelines for merge requests, your merge requests may become stuck in an
+unresolved state or your pipelines may be dropped.
+
+## Start a merge train
+
+To start a merge train:
 
 1. Visit a merge request.
-1. Click the **Start/Add to merge train** button.
+1. Click the **Start merge train** button.
 
 ![Start merge train](img/merge_train_start_v12_0.png)
 
-## How to remove a merge request from a merge train
+Other merge requests can now be added to the train.
+
+## Add a merge request to a merge train
+
+To add a merge request to a merge train:
 
 1. Visit a merge request.
-1. Click the **Remove from merge train** button.
+1. Click the **Add to merge train** button.
 
-![Cancel merge train](img/merge_train_cancel_v12_0.png)
+If pipelines are already running for the merge request, you cannot add the merge request
+to the train. Instead, you can schedule to add the merge request to a merge train **when the latest
+pipeline succeeds**.
 
-## How to view a merge request's current position on the merge train
+![Add to merge train when pipeline succeeds](img/merge_train_start_when_pipeline_succeeds_v12_0.png)
 
-After a merge request has been added to the merge train, the merge request's
-current position will be displayed under the pipeline widget:
+## Remove a merge request from a merge train
 
-![Merge train position indicator](img/merge_train_position_v12_0.png)
+1. Visit a merge request.
+1. Click the **Remove from merge train** button.
 
-## Start/Add to merge train when pipeline succeeds
+![Cancel merge train](img/merge_train_cancel_v12_0.png)
 
-You can add a merge request to a merge train only when the latest pipeline in the
-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.
+If you want to add the merge request to a merge train again later, you can.
 
-In this case, you can schedule to add the merge request to a merge train **when the latest
-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.
+## View a merge request's current position on the merge train
 
-![Add to merge train when pipeline succeeds](img/merge_train_start_when_pipeline_succeeds_v12_0.png)
+After a merge request has been added to the merge train, the merge request's
+current position is displayed under the pipeline widget:
+
+![Merge train position indicator](img/merge_train_position_v12_0.png)
 
 ## Immediately merge a merge request with a merge train
 
-In the case where you have a high-priority merge request (for example, a critical patch) to be merged urgently,
-you can use **Merge Immediately** option for bypassing the merge train.
+If you have a high-priority merge request (for example, a critical patch) that must
+be merged urgently, you can bypass the merge train by using the **Merge Immediately** option.
 This is the fastest option to get the change merged into the target branch.
 
 ![Merge Immediately](img/merge_train_immediate_merge_v12_6.png)
 
-However, every time you merge a merge request immediately, it could affect the
-existing merge train to be reconstructed, specifically, it regenerates expected
-merge commits and pipelines. This means, merging immediately essentially wastes
-CI resources. Because of these downsides, you will be asked to confirm before
-the merge is initiated:
-
-![Merge immediately confirmation dialog](img/merge_train_immediate_merge_confirmation_dialog_v12_6.png)
+CAUTION: **Caution:**
+Each time you merge a merge request immediately, the current merge train
+is recreated and all pipelines restart.
 
 ## Troubleshooting
 
 ### Merge request dropped from the merge train immediately
 
 If a merge request is not mergeable (for example, it's WIP, there is a merge
-conflict, etc), your merge request will be dropped from the merge train automatically.
+conflict, etc.), your merge request will be dropped from the merge train automatically.
 
 In these cases, the reason for dropping the merge request is in the **system notes**.
 
@@ -146,35 +157,30 @@ To check the reason:
 ### Merge When Pipeline Succeeds cannot be chosen
 
 [Merge When Pipeline Succeeds](../../../../user/project/merge_requests/merge_when_pipeline_succeeds.md)
-is unavailable when
-[Pipelines for Merged Results is enabled](../index.md#enabling-pipelines-for-merged-results).
+is currently unavailable when Merge Trains are enabled.
 
-Follow [this issue](https://gitlab.com/gitlab-org/gitlab/issues/12267) to
-track progress on this issue.
+See [the related issue](https://gitlab.com/gitlab-org/gitlab/issues/12267)
+for more information.
 
 ### Merge Train Pipeline cannot be retried
 
 A Merge Train pipeline cannot be retried because the merge request is dropped from the merge train upon failure. For this reason, the retry button does not appear next to the pipeline icon.
 
-In the case of pipeline failure, you should [re-enqueue](#how-to-add-a-merge-request-to-a-merge-train) the merge request to the merge train, which will then initiate a new pipeline.
-
-### Merge Train disturbs your workflow
+In the case of pipeline failure, you should [re-enqueue](#add-a-merge-request-to-a-merge-train) the merge request to the merge train, which will then initiate a new pipeline.
 
-First of all, please check if [merge immediately](#immediately-merge-a-merge-request-with-a-merge-train)
-is available as a workaround in your workflow. This is the most recommended
-workaround you'd be able to take immediately. If it's not available or acceptable,
-please read through this section.
+### Merge Trains feature flag **(PREMIUM ONLY)**
 
-Merge train is enabled by default when you enable [Pipelines for merged results](../index.md),
-however, you can disable this feature by setting the `:disable_merge_trains` feature flag to `enable`.
-When you disable this feature, all existing merge trains are aborted and
-the **Start/Add Merge Train** button no longer appears in merge requests.
+To enable and disable the Merge Trains feature, use the `:disable_merge_trains` feature flag.
 
 To check if the feature flag is enabled on your GitLab instance,
-please ask an administrator to execute the following commands **(CORE ONLY)**:
+ask an administrator to execute the following commands:
 
 ```shell
 > sudo gitlab-rails console                         # Login to Rails console of GitLab instance.
 > Feature.enabled?(:disable_merge_trains)           # Check if it's disabled or not.
 > Feature.enable(:disable_merge_trains)             # Disable Merge Trains.
+> Feature.disable(:disable_merge_trains)            # Enable Merge Trains.
 ```
+
+When you disable this feature, all existing merge trains are cancelled and
+the **Start/Add to Merge Train** button no longer appears in merge requests.