Add overview and use cases for MR-related docs

doc/ci/multi_project_pipeline_graphs.md

+# Multi-Project Pipeline Graphs
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/2121) in
+[GitLab Enterprise Edition Premium 9.3](https://about.gitlab.com/2017/06/22/gitlab-9-3-released/#multi-project-pipeline-graphs).
+
+## Overview
+
+GitLab CI/CD is a powerful continuous integration tool built-in GitLab.
+GitLab CI works not only per project, but also across projects. When you
+configure GitLab CI for your project, you can visualize the stages
+of your [jobs](pipelines.md#jobs) on a chart called [pipeline graph](pipelines.md#pipeline-graphs).
+
+When you set up [GitLab CI/CD](README.md) across multiple projects, you can visualize
+the entire pipeline, including all multi-project stages.
+
+![Multi-project pipeline graph](img/multi_project_pipeline_graph.png)
+
+Multi-Project Pipeline Graphs are useful for larger projects, especially those
+adopting a [microservices architecture](https://about.gitlab.com/2016/08/16/trends-in-version-control-land-microservices/),
+that often have a set of interdependent components which form the complete product.
+
+## Use cases
+
+Let's assume you deploy your web app from different projects in GitLab:
+
+- One for the free version, which has its own pipeline that builds and tests your app
+- One for the paid version adds-ons, which also pass through builds and tests
+- One for the documentation, which also builds, tests, and deploys with an SSG
+
+With Multi-Project Pipeline Graphs, you can visualize the entire pipeline in a
+beautiful and clear chart, including all stages of builds and tests for the three projects.
+
+## How it works
+
+Using the [`CI_JOB_TOKEN` when triggering pipelines](triggers/README.md#ci-job-token), GitLab
+recognizes the source of the job token, and thus internally ties these pipelines
+together which makes it easy to start visualizing their relationships.
+
+Those relationships are displayed in the pipeline graph by showing inbound and
+outbound connections for upstream and downstream pipeline dependencies.

doc/ci/pipelines.md

@@ -186,22 +186,12 @@ by name. The order of severity is:
 
 ![Pipeline mini graph sorting](img/pipelines_mini_graph_sorting.png)
 
-### Multi-project pipelines graphs
+### Multi-Project Pipelines Graphs
 
-> [Introduced][ee-2121] in [GitLab Enterprise Edition Premium][eep] 9.3.
+With [Multi-Project Pipeline Graphs](multi_project_pipeline_graphs.md),
+you can visualize cross-project pipelines.
 
-Using the [`CI_JOB_TOKEN` when triggering pipelines][triggers], GitLab
-recognizes the source of the job token, and thus internally ties these pipelines
-together which makes it easy to start visualizing their relationships.
-
-Those relationships are displayed in the pipeline graph by showing inbound and
-outbound connections for upstream and downstream pipeline dependencies.
-
-![Multi-projects pipelines graphs](img/multi_project_pipelines_graph.png)
-
-This is useful for larger projects, especially those adopting a micro-services
-architecture, that often have a set of interdependent components which form the
-complete product.
+It is available only in [GitLab Enterprise Edition Premium][eep].
 
 ## How the pipeline duration is calculated
 
@@ -244,7 +234,7 @@ respective link in the [Pipelines settings] page.
 [manual]: yaml/README.md#manual
 [env-manual]: environments.md#manually-deploying-to-environments
 [stages]: yaml/README.md#stages
-[runners]: runners/README.html
+[runners]: runners/README.md
 [pipelines settings]: ../user/project/pipelines/settings.md
 [triggers]: triggers/README.md#ci-job-token
 [ce-5742]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5742

doc/user/project/merge_requests/code_quality_diff.md

@@ -2,12 +2,28 @@
 
 > [Introduced][ee-1984] in [GitLab Enterprise Edition Starter][ee] 9.3.
 
+## Overview
+
 If you are using [GitLab CI][ci], you can analyze your source code quality using
 the [Code Climate][cc] analyzer [Docker image][cd]. Going a step further, GitLab
 can show the Code Climate report right in the merge request widget area.
 
 ![Code Quality Widget][quality-widget]
 
+## Use cases
+
+For instance, consider the following workflow:
+
+1. Your backend team member starts a new implementation for making certain feature in your app faster
+1. With Code Quality reports, they analize how their implementation is impacting the code quality
+1. The metrics show that their code degrade the quality in 10 points
+1. You ask a co-worker to help them with this modification
+1. They both work on the changes until Code Quality report displays no degradations, only improvements
+1. You approve the merge request and authorize its deployment to staging
+1. Once verified, their changes are deployed to production
+
+## How it works
+
 In order for the report to show in the merge request, you need to specify a
 `codeclimate` job (exact name) that will analyze the code and upload the resulting
 `codeclimate.json` as an artifact. GitLab will then check this file and show
@@ -18,7 +34,7 @@ If the Code Climate report doesn't have anything to compare to, no information
 will be displayed in the merge request area. That is the case when you add the
 `codeclimate` job in your `.gitlab-ci.yml` for the very first time.
 Consecutive merge requests will have something to compare to and the code quality
-diff will be shown properly.
+report will be shown properly.
 
 For more information on how the `codeclimate` job should look like, check the
 example on [analyzing a project's code quality with Code Climate CLI][cc-docs].

doc/user/project/merge_requests/index.md

@@ -3,6 +3,59 @@
 Merge requests allow you to exchange changes you made to source code and
 collaborate with other people on the same project.
 
+## Overview
+
+A Merge Request (**MR**) is the basis of GitLab as a code collaboration
+and version control platform.
+Is it simple as the name implies: a _request_ to _merge_ one branch into another.
+
+With GitLab merge requests, you can:
+
+- Compare the changes between two [branches](https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell#_git_branching)
+- Discuss and review the proposed modifications inline
+- Live preview the changes when [Review Apps](../../../ci/review_apps/index.md) is configured for your project
+- Build, test, and deploy your code is a per-branch basis with built-in [GitLab CI/CD](../../../ci/README.md)
+- Prevent the merge request from being merged before it's ready with [WIP MRs](#work-in-progress-merge-requests)
+- View the deployment process through [Pipeline Graphs](../../../ci/pipelines.md#pipeline-graphs)
+- [Automatically close the issue(s)](../../project/issues/closing_issues.md#via-merge-request) that originated the implementation proposed in the merge request
+- Assign it to any registered user, and change the assignee how many times you need
+- Assign a [milestone](../../project/milestones/index.md) and track the development of a broader implementation
+- Organize your issues and merge requests consistently throughout the project with [labels](../../project/labels.md)
+- Add a time estimation and the time spent with that merge request with [Time Tracking](../../../workflow/time_tracking.html#time-tracking)
+- [Resolve merge conflicts from the UI](#resolve-conflicts)
+
+With [GitLab Enterprise Edition][ee], you can also:
+
+- View the deployment process across projects with [Multi-Project Pipeline Graphs](../../../ci/multi_project_pipeline_graphs.md) (available only in GitLab Enterprise Edition Premium)
+- Request [approvals](#merge-request-approvals) from your managers (available in GitLab Enterprise Edition Starter)
+- Enable [fast-forward merge requests](#fast-forward-merge-requests) (available in GitLab Enterprise Edition Starter)
+- [Squash and merge](#squash-and-merge) for a cleaner commit history (available in GitLab Enterprise Edition Starter)
+- Enable [semi-linear history merge requests](#semi-linear-history-merge-requests) as another security layer to guarantee the pipeline is passing in the target branch (available in GitLab Enterprise Edition Starter)
+- Analise the impact of your changes with [Code Quality reports](#code-quality-reports) (available only in GitLab Enterprise Edition Starter)
+
+## Use cases
+
+A. Consider you are a software developer working in a team:
+
+1. You checkout a new branch, and submit your changes through a merge request
+1. You gather feedback from your team
+1. You work on the implementation optimizing code with [Code Quality reports](#code-quality-reports)
+1. You build and test your changes with GitLab CI/CD
+1. You request the approval from your manager
+1. Your manager pushes a commit with his final review and set the merge request to [merge when pipeline succeeds](#merge-when-pipeline-succeeds)
+1. Your changes get deployed to production with [manual actions](../../../ci/yaml/README.md#manual-actions) for GitLab CI/CD
+1. Your implementations were successfully shipped to your customer
+
+B. Consider you're a web developer writing a webpage for your company's website:
+
+1. You checkout a new branch, and submit a new page through a merge request
+1. You gather feedback from your reviewers
+1. Your changes are previewed with [Review Apps](../../../ci/review_apps/index.md)
+1. You request your web designers for their implementation
+1. You request the approval from your manager
+1. Once approved, your merge request is [squashed and merged](#squash-and-merge), and [deployed to staging with GitLab Pages](https://about.gitlab.com/2016/08/26/ci-deployment-and-environments/)
+1. Your production team [cherry picks](#cherry-pick-changes) the merge commit into production
+
 ## Authorization for merge requests
 
 There are two main ways to have a merge request flow with GitLab:
@@ -91,7 +144,7 @@ list of approvers that will need to approve every merge request in a project.
 
 A merge commit is created for every merge, but the branch is only merged if
 a fast-forward merge is possible. This ensures that if the merge request build
-suceedeed, the target branch build will also succeed after merging.
+succeeded, the target branch build will also succeed after merging.
 
 Navigate to a project's settings, select the **Merge commit with semi-linear
 history** option under **Merge Requests: Merge method** and save your changes.
@@ -105,7 +158,7 @@ creating merge commits, you can configure this on a per-project basis.
 
 [Read more about fast-forward merge requests.](fast_forward_merge.md)
 
-## Code quality diff
+## Code Quality reports
 
 > Introduced in [GitLab Enterprise Edition Starter][products] 9.3.
 
@@ -113,7 +166,16 @@ If you are using [GitLab CI][ci], you can analyze your source code quality using
 the [Code Climate][cc] analyzer [Docker image][cd]. Going a step further, GitLab
 can show the Code Climate report right in the merge request widget area.
 
-[Read more about code quality diff.](code_quality_diff.md)
+[Read more about Code Quality reports.](code_quality_diff.md)
+
+## Live preview with Review Apps
+
+If you configured [Review Apps](https://about.gitlab.com/features/review-apps/) for your project,
+you can preview the changes submitted to a feature-branch through a merge request
+in a per-branch basis. No need to checkout the branch, install and preview locally;
+all your changes will be available to preview by anyone with the Review Apps link.
+
+[Read more about Review Apps.](../../../ci/review_apps/index.md)
 
 ## Ignore whitespace changes in Merge Request diff view
 
@@ -219,3 +281,4 @@ git checkout origin/merge-requests/1
 [ci]: ../../../ci/README.md
 [cc]: https://codeclimate.com/
 [cd]: https://hub.docker.com/r/codeclimate/codeclimate/
+[ee]: https://about.gitlab.com/gitlab-ee/ "GitLab Enterprise Edition"

doc/user/project/merge_requests/merge_request_approvals.md

 # Merge request approvals
 
-> Introduced in GitLab Enterprise Edition 7.13.
+> Introduced in [GitLab Enterprise Edition 7.12](https://about.gitlab.com/2015/06/22/gitlab-7-12-released/#merge-request-approvers-ee-only), available in [GitLab Enterprise Edition Starter](https://about.gitlab.com/gitlab-ee/).
+
+## Overview
 
 If you want to make sure every merge request is approved by one or more
 people, you can enforce this workflow by using merge request approvals.
+
 Merge request approvals allow you to set the number of necessary approvals
 and predefine a list of approvers that will need to approve every
 merge request in a project.
 
+## Use cases
+
+There are numerous use cases for merge request approvals. For instance,
+let's consider you're a backend developer working in a team:
+
+1. You submit changes to your project via merge request
+1. You gather feedback from your team members in the merge request
+1. You build, test, and deploy your app with [GitLab CI/CD](../../../ci/README.md)
+1. Once everything is ready to ship, you add your manager and the project manager as approvers to that merge request
+1. Your approvers get a notification and review your modifications
+1. You need to address your managers' comments, so you push again to your branch
+1. Once you pushed, that merge request will need another round of approvals
+1. You ask your managers again for their approval
+1. They approve and merge
+
+This example workflow prevents your implementations from being merged before getting approvals from both managers.
+
 ## Configuring Approvals
 
 You can configure the approvals in the project settings, under merge requests.