Add links to new docs in merge_requests.md and workflow/README.md

app/views/projects/merge_requests/show/_how_to_merge.html.haml

@@ -47,8 +47,9 @@
             Note that pushing to GitLab requires write access to this repository.
         %p
           %strong Tip:
+          = succeed '.' do
             You can also checkout merge requests locally by
-          %a{href: 'https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/workflow/merge_requests.md#checkout-merge-requests-locally', target: '_blank'} following these guidelines
+            = link_to 'following these guidelines', help_page_path('user/project/merge_requests.md', anchor: "checkout-merge-requests-locally"), target: '_blank'
 
 :javascript
   $(function(){

doc/user/project/merge_requests.md

@@ -3,9 +3,97 @@
 Merge requests allow you to exchange changes you made to source code and
 collaborate with other people on the same project.
 
-## Checkout merge requests locally
+## Authorization for merge requests
 
-### By adding a git alias
+There are two main ways to have a merge request flow with GitLab:
+
+1. Working with [protected branches][] in a single repository
+1. Working with forks of an authoritative project
+
+[Learn more about the authorization for merge requests.](merge_requests/authorization_for_merge_requests.md)
+
+## Cherry-pick changes
+
+Cherry-pick any commit in the UI by simply clicking the **Cherry-pick** button
+in a merged merge requests or a commit.
+
+[Learn more about cherry-picking changes.](merge_requests/cherry_pick_changes.md)
+
+## Merge when build succeeds
+
+When reviewing a merge request that looks ready to merge but still has one or
+more CI builds running, you can set it to be merged automatically when all
+builds succeed. This way, you don't have to wait for the builds to finish and
+remember to merge the request manually.
+
+[Learn more about merging when build succeeds.](merge_requests/merge_when_build_succeeds.md)
+
+## Resolve discussion comments in merge requests reviews
+
+Keep track of the progress during a code review with resolving comments.
+Resolving comments prevents you from forgetting to address feedback and lets
+you hide discussions that are no longer relevant.
+
+[Read more about resolving discussion comments in merge requests reviews.](merge_requests/merge_request_discussion_resolution.md)
+
+## Resolve conflicts
+
+When a merge request has conflicts, GitLab may provide the option to resolve
+those conflicts in the GitLab UI.
+
+[Learn more about resolving merge conflicts in the UI.](merge_requests/resolve_conflicts.md)
+
+## Revert changes
+
+GitLab implements Git's powerful feature to revert any commit with introducing
+a **Revert** button in merge requests and commit details.
+
+[Learn more about reverting changes in the UI](merge_requests/revert_changes.md)
+
+## Merge requests versions
+
+Every time you push to a branch that is tied to a merge request, a new version
+of merge request diff is created. When you visit a merge request that contains
+more than one pushes, you can select and compare the versions of those merge
+request diffs.
+
+[Read more about the merge requests versions.](merge_requests/versions.md)
+
+## Work In Progress merge requests
+
+To prevent merge requests from accidentally being accepted before they're
+completely ready, GitLab blocks the "Accept" button for merge requests that
+have been marked as a **Work In Progress**.
+
+[Learn more about settings a merge request as "Work In Progress".](merge_requests/work_in_progress_merge_requests.md)
+
+## Ignore whitespace changes in Merge Request diff view
+
+If you click the **Hide whitespace changes** button, you can see the diff
+without whitespace changes (if there are any). This is also working when on a
+specific commit page.
+
+![MR diff](merge_requests/img/merge_request_diff.png)
+
+>**Tip:**
+You can append `?w=1` while on the diffs page of a merge request to ignore any
+whitespace changes.
+
+## Tips
+
+Here are some tips that will help you be more efficient with merge requests in
+the command line.
+
+> **Note:**
+This section might move in its own document in the future.
+
+### Checkout merge requests locally
+
+A merge request contains all the history from a repository, plus the additional
+commits added to the branch associated with the merge request. Here's a few
+tricks to checkout a merge request locally.
+
+#### Checkout locally by adding a git alias
 
 Add the following alias to your `~/.gitconfig`:
 
@@ -14,17 +102,21 @@ Add the following alias to your `~/.gitconfig`:
     mr = !sh -c 'git fetch $1 merge-requests/$2/head:mr-$1-$2 && git checkout mr-$1-$2' -
 ```
 
-Now you can check out a particular merge request from any repository and any remote, e.g. to check out a merge request number 5 as shown in GitLab from the `upstream` remote, do:
+Now you can check out a particular merge request from any repository and any
+remote. For example, to check out the merge request with ID 5 as shown in GitLab
+from the `upstream` remote, do:
 
 ```
-$ git mr upstream 5
+git mr upstream 5
 ```
 
-This will fetch the merge request into a local `mr-upstream-5` branch and check it out.
+This will fetch the merge request into a local `mr-upstream-5` branch and check
+it out.
 
-### By modifying `.git/config` for a given repository
+#### Checkout locally by modifying `.git/config` for a given repository
 
-Locate the section for your GitLab remote in the `.git/config` file. It looks like this:
+Locate the section for your GitLab remote in the `.git/config` file. It looks
+like this:
 
 ```
 [remote "origin"]
@@ -32,9 +124,19 @@ Locate the section for your GitLab remote in the `.git/config` file. It looks li
   fetch = +refs/heads/*:refs/remotes/origin/*
 ```
 
-Now add the line `fetch = +refs/merge-requests/*/head:refs/remotes/origin/merge-requests/*` to this section.
+You can open the file with:
+
+```
+git config -e
+```
+
+Now add the following line to the above section:
+
+```
+fetch = +refs/merge-requests/*/head:refs/remotes/origin/merge-requests/*
+```
 
-It should look like this:
+In the end, it should look like this:
 
 ```
 [remote "origin"]
@@ -46,31 +148,19 @@ It should look like this:
 Now you can fetch all the merge requests:
 
 ```
-$ git fetch origin
+git fetch origin
+
+...
 From https://gitlab.com/gitlab-org/gitlab-ce.git
  * [new ref]         refs/merge-requests/1/head -> origin/merge-requests/1
  * [new ref]         refs/merge-requests/2/head -> origin/merge-requests/2
 ...
 ```
 
-To check out a particular merge request:
+And to check out a particular merge request:
 
 ```
-$ git checkout origin/merge-requests/1
+git checkout origin/merge-requests/1
 ```
 
-## Ignore whitespace changes in Merge Request diff view
-
-![MR diff](merge_requests/img/merge_request_diff.png)
-
-If you click the "Hide whitespace changes" button, you can see the diff without whitespace changes.
-
-![MR diff without whitespace](merge_requests/img/merge_request_diff_without_whitespace.png)
-
-It is also working on commits compare view.
-
-![Commit Compare](merge_requests/img/commit_compare.png)
-
-## Merge Requests versions
-
-Select an older revision to from the version dropdown.
+[protected branches]: protected_branches.md

doc/workflow/README.md

 # Workflow
 
-- [Authorization for merge requests](authorization_for_merge_requests.md)
 - [Change your time zone](timezone.md)
 - [Description templates](../user/project/description_templates.md)
 - [Feature branch workflow](workflow.md)
@@ -22,10 +21,14 @@
 - [Releases](releases.md)
 - [Milestones](milestones.md)
 - [Merge Requests](../user/project/merge_requests.md)
-- [Revert changes](revert_changes.md)
-- [Cherry-pick changes](cherry_pick_changes.md)
-- ["Work In Progress" Merge Requests](wip_merge_requests.md)
-- [Merge When Build Succeeds](merge_when_build_succeeds.md)
+  - [Authorization for merge requests](../user/project/merge_requests/authorization_for_merge_requests.md)
+  - [Cherry-pick changes](../user/project/merge_requests/cherry_pick_changes.md)
+  - [Merge when build succeeds](../user/project/merge_requests/merge_when_build_succeeds.md)
+  - [Resolve discussion comments in merge requests reviews](../user/project/merge_requests/merge_request_discussion_resolution.md)
+  - [Resolve merge conflicts in the UI](../user/project/merge_requests/resolve_conflicts.md)
+  - [Revert changes in the UI](../user/project/merge_requests/revert_changes.md)
+  - [Merge requests versions](../user/project/merge_requests/versions.md)
+  - ["Work In Progress" merge requests](../user/project/merge_requests/work_in_progress_merge_requests.md)
 - [Manage large binaries with Git LFS](lfs/manage_large_binaries_with_git_lfs.md)
 - [Importing from SVN, GitHub, BitBucket, etc](importing/README.md)
 - [Todos](todos.md)