Clarify documentation for new featuredocs-run-pipeline-on-merge-ref

Apply suggestion to doc/ci/merge_request_pipelines/index.md

Apply suggestion to doc/ci/merge_request_pipelines/index.md

Apply suggestion to doc/ci/merge_request_pipelines/index.md

Apply suggestion to doc/ci/merge_request_pipelines/index.md

Apply suggestion to doc/ci/merge_request_pipelines/index.md

Apply suggestion to doc/ci/merge_request_pipelines/index.md

Apply suggestion to doc/ci/merge_request_pipelines/index.md

Apply suggestion to doc/ci/merge_request_pipelines/index.md

Apply suggestion to doc/ci/merge_request_pipelines/index.md

Apply suggestion to doc/ci/merge_request_pipelines/index.md

Apply suggestion to doc/ci/merge_request_pipelines/index.md

Apply suggestion to doc/ci/merge_request_pipelines/index.md

Apply suggestion to doc/ci/merge_request_pipelines/index.md

ok

ok

ok

1 files changed, 44 insertions, 39 deletions

diff --git a/doc/ci/merge_request_pipelines/index.md b/doc/ci/merge_request_pipelines/index.md
index 9ee3d8750fb..69739bb383e 100644
--- a/doc/ci/merge_request_pipelines/index.md
+++ b/doc/ci/merge_request_pipelines/index.md
@@ -2,14 +2,16 @@
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/15310) in GitLab 11.6.
 
-Usually, when you create a new merge request, a pipeline runs on the
+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 checking the new changes.
+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.
 
 With pipelines for merge requests, you can design a specific pipeline structure
-for merge requests.
+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.
 
 ## Configuring pipelines for merge requests
 
@@ -50,9 +52,9 @@ After the 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 `test` job.
-Since the `build` and `deploy` job doesn't have the `only: merge_requests` parameter,
-deployment jobs will not happen in the merge request.
+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:
@@ -61,53 +63,47 @@ when a merge request was created or updated. For example:
 
 ## Run pipeline on merged code before merging **[PREMIUM]**
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/7380) in GitLab 11.10.
+> [GitLab Premium](https://about.gitlab.com/pricing/) 11.10.
 
-Teams need to keep master "green". It's a huge pain when someone merges a MR that
-breaks master because they didn't know of some conflict and their MR's pipeline was green.
-It's great that master has its own pipeline with tests so it won't accidentally
-deploy a broken codebase, but it sucks that master is left broken, and any MR based
-on master will now fail as well.
+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.
 
-In order to keep master green, we can run a pipeline on the state that master
-would be in after the merge - by combining the source and target branch into a new ref,
-then running a pipeline on that ref, we can better test that the combined result is also valid
-(at least moreso than if we test only the source branch.) To achieve this,
-we introduced this feature that pipelines for merge requests now always run by default
-on the merged result: where the source and target branches are combined into a new ref
-and a pipeline is run that validates the result prior to merging.
+From GitLab 11.10, pipelines for merge requests run by default
+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/merge_request_pipeline.png)
 
-(*Screenshot of a pipeline which ran on a merge ref*)
+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.
 
-There are some cases where creating a combined ref is not possible or not wanted;
-in these scenarios (for example, a source branch that has conflicts with the target, or a MR that is still in WIP status)
-it fallbacks to a "detached" state and run on the source branch ref - just like it works as well as a normal branch pipeline runs.
-Being in this detached state serves as a warning that you are working in a situation
-where you may eventually have merge problems, and helps highlight that you should
-get out of WIP status or resolve your merge conflicts as soon as reasonable.
+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.
 
-### How to enable this feature
+### Enabling this feature
 
-This feature is an optional behavior that can be turned on at the project level.
-It is **off** by default until we have better contention handling (See https://gitlab.com/gitlab-org/gitlab-ee/issues/9186).
+This feature disabled by default until we resolve issues with [contention handling](https://gitlab.com/gitlab-org/gitlab-ee/issues/9186). It can be enabled at the project level:
 
-1. Visit **Settings > General > Merge requests**
-1. Check **Merge pipelines will try to validate the post-merge result prior to merging** checkbox
-1. Click **Save changes** button
+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.
 
 ![Merge request pipeline config](img/merge_request_pipeline_config.png)
 
-(*Screenshot of the checkbox*)
-
 ### Limitations
 
-- This feature requires [GitLab-Runner](https://gitlab.com/gitlab-org/gitlab-runner) 11.9+
-- This feature requires [Gitaly](https://gitlab.com/gitlab-org/gitaly) 1.21.0+
-- If, after the merge request pipeline succeeds, the target branch has moved forward, then the result of the pipeline is stale and must be retried. In busy repos this can become a problem because you're nearly guaranteed that the target branch will have moved ahead. This is subject to change which is [planned](https://gitlab.com/gitlab-org/gitlab-ee/issues/9186) in one of the future iterations.
-- Forking/cross-repo workflows are not supported, currently. This is subject to change which is issued in https://gitlab.com/gitlab-org/gitlab-ee/issues/9713.
-- This feature is not available for [fast forward merges](https://docs.gitlab.com/ee/user/project/merge_requests/fast_forward_merge.html) yet. This is subject to change which is issued in https://gitlab.com/gitlab-org/gitlab-ce/issues/58226.
+- This feature requires [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-runner) 11.9 or newer.
+- This feature requires [Gitaly](https://gitlab.com/gitlab-org/gitaly) 1.21.0 or newer.
+- After the merge request pipeline succeeds, if the target branch has moved forward, the result of the pipeline is stale and must be retried. In busy repos, this can become a problem as it is highly probable that the target branch will have moved ahead. Improvements are [planned](https://gitlab.com/gitlab-org/gitlab-ee/issues/9186) for future versions of GitLab.
+- Forking/cross-repo workflows are not currently supported. To follow progress, see [#9713](https://gitlab.com/gitlab-org/gitlab-ee/issues/9713).
+- 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).
 
 ## Excluding certain jobs
 
@@ -184,3 +180,12 @@ External users could steal secret variables from the parent project by modifying
 We're discussing a secure solution of running pipelines for merge requests
 that submitted from forked projects,
 see [the issue about the permission extension](https://gitlab.com/gitlab-org/gitlab-ce/issues/23902).
+
+## Additional predefined variables
+
+By using pipelines for merge requests, GitLab exposes additional predefined variables to the pipeline jobs.
+Those variables contain information of the associated merge request, so that it's useful
+to integrate your job with [GitLab Merge Request API](https://docs.gitlab.com/ee/api/merge_requests.html).
+
+You can find the list of avilable variables in [the reference sheet](https://docs.gitlab.com/ee/ci/variables/predefined_variables.html).
+The variable names begin with the `CI_MERGE_REQUEST_` prefix.