Merge branch '21857-refactor-merge-requests-documentation' into 'master'

Refactor merge requests documentation

## What does this MR do?

Add more information on merge requests.

## Moving docs to a new location?

See the guidelines: http://docs.gitlab.com/ce/development/doc_styleguide.html#changing-document-location

- [x] Make sure the old link is not removed and has its contents replaced with a link to the new location.
- [x] Make sure internal links pointing to the document in question are not broken.
- [x] Search and replace any links referring to old docs in GitLab Rails app, specifically under the `app/views/` directory.
- [x] If working on CE, submit an MR to EE with the changes as well.

---

Closes https://gitlab.com/gitlab-org/gitlab-ce/issues/21857

See merge request !6202

38 files changed, 445 insertions, 286 deletions

diff --git a/app/views/projects/_merge_request_settings.html.haml b/app/views/projects/_merge_request_settings.html.haml
index 14eb47089b1..80053dd501b 100644
--- a/app/views/projects/_merge_request_settings.html.haml
+++ b/app/views/projects/_merge_request_settings.html.haml
@@ -11,4 +11,4 @@
           %br
           %span.descr
             Builds need to be configured to enable this feature.
-            = link_to icon('question-circle'), help_page_path('workflow/merge_requests', anchor: 'only-allow-merge-requests-to-be-merged-if-the-build-succeeds')
+            = link_to icon('question-circle'), help_page_path('user/project/merge_requests/merge_when_build_succeeds', anchor: 'only-allow-merge-requests-to-be-merged-if-the-build-succeeds')
diff --git a/app/views/projects/merge_requests/show/_how_to_merge.html.haml b/app/views/projects/merge_requests/show/_how_to_merge.html.haml
index b727efaa6a6..571e4dd1b1a 100644
--- a/app/views/projects/merge_requests/show/_how_to_merge.html.haml
+++ b/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:
-          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
+          = succeed '.' do
+            You can also checkout merge requests locally by
+            = link_to 'following these guidelines', help_page_path('user/project/merge_requests.md', anchor: "checkout-merge-requests-locally"), target: '_blank'
 
 :javascript
   $(function(){
diff --git a/doc/intro/README.md b/doc/intro/README.md
index 1850031eb26..71fef50ceb4 100644
--- a/doc/intro/README.md
+++ b/doc/intro/README.md
@@ -23,9 +23,9 @@ Create merge requests and review code.
 - [Fork a project and contribute to it](../workflow/forking_workflow.md)
 - [Create a new merge request](../gitlab-basics/add-merge-request.md)
 - [Automatically close issues from merge requests](../customization/issue_closing.md)
-- [Automatically merge when your builds succeed](../workflow/merge_when_build_succeeds.md)
-- [Revert any commit](../workflow/revert_changes.md)
-- [Cherry-pick any commit](../workflow/cherry_pick_changes.md)
+- [Automatically merge when your builds succeed](../user/project/merge_requests/merge_when_build_succeeds.md)
+- [Revert any commit](../user/project/merge_requests/revert_changes.md)
+- [Cherry-pick any commit](../user/project/merge_requests/cherry_pick_changes.md)
 
 ## Test and Deploy
 
diff --git a/doc/user/project/merge_requests.md b/doc/user/project/merge_requests.md
new file mode 100644
index 00000000000..f79535d1542
--- /dev/null
+++ b/doc/user/project/merge_requests.md
@@ -0,0 +1,166 @@
+# Merge Requests
+
+Merge requests allow you to exchange changes you made to source code and
+collaborate with other people on the same project.
+
+## Authorization for merge requests
+
+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`:
+
+```
+[alias]
+    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. For example, to check out the merge request with ID 5 as shown in GitLab
+from the `upstream` remote, do:
+
+```
+git mr upstream 5
+```
+
+This will fetch the merge request into a local `mr-upstream-5` branch and check
+it out.
+
+#### 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:
+
+```
+[remote "origin"]
+  url = https://gitlab.com/gitlab-org/gitlab-ce.git
+  fetch = +refs/heads/*:refs/remotes/origin/*
+```
+
+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/*
+```
+
+In the end, it should look like this:
+
+```
+[remote "origin"]
+  url = https://gitlab.com/gitlab-org/gitlab-ce.git
+  fetch = +refs/heads/*:refs/remotes/origin/*
+  fetch = +refs/merge-requests/*/head:refs/remotes/origin/merge-requests/*
+```
+
+Now you can fetch all the merge requests:
+
+```
+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
+...
+```
+
+And to check out a particular merge request:
+
+```
+git checkout origin/merge-requests/1
+```
+
+[protected branches]: protected_branches.md
diff --git a/doc/user/project/merge_requests/authorization_for_merge_requests.md b/doc/user/project/merge_requests/authorization_for_merge_requests.md
new file mode 100644
index 00000000000..59b3fe7242c
--- /dev/null
+++ b/doc/user/project/merge_requests/authorization_for_merge_requests.md
@@ -0,0 +1,56 @@
+# Authorization for Merge requests
+
+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.
+
+## Protected branch flow
+
+With the protected branch flow everybody works within the same GitLab project.
+
+The project maintainers get Master access and the regular developers get
+Developer access.
+
+The maintainers mark the authoritative branches as 'Protected'.
+
+The developers push feature branches to the project and create merge requests
+to have their feature branches reviewed and merged into one of the protected
+branches.
+
+By default, only users with Master access can merge changes into a protected
+branch.
+
+**Advantages**
+
+- Fewer projects means less clutter.
+- Developers need to consider only one remote repository.
+
+**Disadvantages**
+
+- Manual setup of protected branch required for each new project
+
+## Forking workflow
+
+With the forking workflow the maintainers get Master access and the regular
+developers get Reporter access to the authoritative repository, which prohibits
+them from pushing any changes to it.
+
+Developers create forks of the authoritative project and push their feature
+branches to their own forks.
+
+To get their changes into master they need to create a merge request across
+forks.
+
+**Advantages**
+
+- In an appropriately configured GitLab group, new projects automatically get
+  the required access restrictions for regular developers: fewer manual steps
+  to configure authorization for new projects.
+
+**Disadvantages**
+
+- The project need to keep their forks up to date, which requires more advanced
+  Git skills (managing multiple remotes).
+
+[protected branches]: ../protected_branches.md
diff --git a/doc/user/project/merge_requests/cherry_pick_changes.md b/doc/user/project/merge_requests/cherry_pick_changes.md
new file mode 100644
index 00000000000..64b94d81024
--- /dev/null
+++ b/doc/user/project/merge_requests/cherry_pick_changes.md
@@ -0,0 +1,52 @@
+# Cherry-pick changes
+
+> [Introduced][ce-3514] in GitLab 8.7.
+
+---
+
+GitLab implements Git's powerful feature to [cherry-pick any commit][git-cherry-pick]
+with introducing a **Cherry-pick** button in Merge Requests and commit details.
+
+## Cherry-picking a Merge Request
+
+After the Merge Request has been merged, a **Cherry-pick** button will be available
+to cherry-pick the changes introduced by that Merge Request:
+
+![Cherry-pick Merge Request](img/cherry_pick_changes_mr.png)
+
+---
+
+You can cherry-pick the changes directly into the selected branch or you can opt to
+create a new Merge Request with the cherry-pick changes:
+
+![Cherry-pick Merge Request modal](img/cherry_pick_changes_mr_modal.png)
+
+## Cherry-picking a Commit
+
+You can cherry-pick a Commit from the Commit details page:
+
+![Cherry-pick commit](img/cherry_pick_changes_commit.png)
+
+---
+
+Similar to cherry-picking a Merge Request, you can opt to cherry-pick the changes
+directly into the target branch or create a new Merge Request to cherry-pick the
+changes:
+
+![Cherry-pick commit modal](img/cherry_pick_changes_commit_modal.png)
+
+---
+
+Please note that when cherry-picking merge commits, the mainline will always be the
+first parent. If you want to use a different mainline then you need to do that
+from the command line.
+
+Here is a quick example to cherry-pick a merge commit using the second parent as the
+mainline:
+
+```bash
+git cherry-pick -m 2 7a39eb0
+```
+
+[ce-3514]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/3514 "Cherry-pick button Merge Request"
+[git-cherry-pick]: https://git-scm.com/docs/git-cherry-pick "Git cherry-pick documentation"
diff --git a/doc/workflow/img/cherry_pick_changes_commit.png b/doc/user/project/merge_requests/img/cherry_pick_changes_commit.png
index 7fb68cc9e9b..7fb68cc9e9b 100644
--- a/doc/workflow/img/cherry_pick_changes_commit.png
+++ b/doc/user/project/merge_requests/img/cherry_pick_changes_commit.png
diff --git a/doc/workflow/img/cherry_pick_changes_commit_modal.png b/doc/user/project/merge_requests/img/cherry_pick_changes_commit_modal.png
index 5267e04562f..5267e04562f 100644
--- a/doc/workflow/img/cherry_pick_changes_commit_modal.png
+++ b/doc/user/project/merge_requests/img/cherry_pick_changes_commit_modal.png
diff --git a/doc/workflow/img/cherry_pick_changes_mr.png b/doc/user/project/merge_requests/img/cherry_pick_changes_mr.png
index 975fb13e463..975fb13e463 100644
--- a/doc/workflow/img/cherry_pick_changes_mr.png
+++ b/doc/user/project/merge_requests/img/cherry_pick_changes_mr.png
diff --git a/doc/workflow/img/cherry_pick_changes_mr_modal.png b/doc/user/project/merge_requests/img/cherry_pick_changes_mr_modal.png
index 6c003bacbe3..6c003bacbe3 100644
--- a/doc/workflow/img/cherry_pick_changes_mr_modal.png
+++ b/doc/user/project/merge_requests/img/cherry_pick_changes_mr_modal.png
diff --git a/doc/workflow/merge_requests/commit_compare.png b/doc/user/project/merge_requests/img/commit_compare.png
index 0e4a2b23c04..0e4a2b23c04 100644
--- a/doc/workflow/merge_requests/commit_compare.png
+++ b/doc/user/project/merge_requests/img/commit_compare.png
diff --git a/doc/user/project/merge_requests/img/merge_request_diff.png b/doc/user/project/merge_requests/img/merge_request_diff.png
new file mode 100644
index 00000000000..06ee4908edc
--- /dev/null
+++ b/doc/user/project/merge_requests/img/merge_request_diff.png
diff --git a/doc/workflow/merge_when_build_succeeds/enable.png b/doc/user/project/merge_requests/img/merge_when_build_succeeds_enable.png
index b86e6d7b3fd..b86e6d7b3fd 100644
--- a/doc/workflow/merge_when_build_succeeds/enable.png
+++ b/doc/user/project/merge_requests/img/merge_when_build_succeeds_enable.png
diff --git a/doc/user/project/merge_requests/img/merge_when_build_succeeds_only_if_succeeds_msg.png b/doc/user/project/merge_requests/img/merge_when_build_succeeds_only_if_succeeds_msg.png
new file mode 100644
index 00000000000..6b9756b7418
--- /dev/null
+++ b/doc/user/project/merge_requests/img/merge_when_build_succeeds_only_if_succeeds_msg.png
diff --git a/doc/workflow/merge_requests/only_allow_merge_if_build_succeeds.png b/doc/user/project/merge_requests/img/merge_when_build_succeeds_only_if_succeeds_settings.png
index 18bebf5fe92..18bebf5fe92 100644
--- a/doc/workflow/merge_requests/only_allow_merge_if_build_succeeds.png
+++ b/doc/user/project/merge_requests/img/merge_when_build_succeeds_only_if_succeeds_settings.png
diff --git a/doc/workflow/merge_when_build_succeeds/status.png b/doc/user/project/merge_requests/img/merge_when_build_succeeds_status.png
index f3ea61d8147..f3ea61d8147 100644
--- a/doc/workflow/merge_when_build_succeeds/status.png
+++ b/doc/user/project/merge_requests/img/merge_when_build_succeeds_status.png
diff --git a/doc/workflow/img/revert_changes_commit.png b/doc/user/project/merge_requests/img/revert_changes_commit.png
index e7194fc3504..e7194fc3504 100644
--- a/doc/workflow/img/revert_changes_commit.png
+++ b/doc/user/project/merge_requests/img/revert_changes_commit.png
diff --git a/doc/workflow/img/revert_changes_commit_modal.png b/doc/user/project/merge_requests/img/revert_changes_commit_modal.png
index c660ec7eaec..c660ec7eaec 100644
--- a/doc/workflow/img/revert_changes_commit_modal.png
+++ b/doc/user/project/merge_requests/img/revert_changes_commit_modal.png
diff --git a/doc/workflow/img/revert_changes_mr.png b/doc/user/project/merge_requests/img/revert_changes_mr.png
index 3002f0ac1c5..3002f0ac1c5 100644
--- a/doc/workflow/img/revert_changes_mr.png
+++ b/doc/user/project/merge_requests/img/revert_changes_mr.png
diff --git a/doc/workflow/img/revert_changes_mr_modal.png b/doc/user/project/merge_requests/img/revert_changes_mr_modal.png
index c6aaeecc8a6..c6aaeecc8a6 100644
--- a/doc/workflow/img/revert_changes_mr_modal.png
+++ b/doc/user/project/merge_requests/img/revert_changes_mr_modal.png
diff --git a/doc/user/project/merge_requests/img/versions.png b/doc/user/project/merge_requests/img/versions.png
new file mode 100644
index 00000000000..f279ccd7ce3
--- /dev/null
+++ b/doc/user/project/merge_requests/img/versions.png
diff --git a/doc/workflow/wip_merge_requests/blocked_accept_button.png b/doc/user/project/merge_requests/img/wip_blocked_accept_button.png
index 89c458aa8d9..89c458aa8d9 100644
--- a/doc/workflow/wip_merge_requests/blocked_accept_button.png
+++ b/doc/user/project/merge_requests/img/wip_blocked_accept_button.png
diff --git a/doc/workflow/wip_merge_requests/mark_as_wip.png b/doc/user/project/merge_requests/img/wip_mark_as_wip.png
index 9c37354a653..9c37354a653 100644
--- a/doc/workflow/wip_merge_requests/mark_as_wip.png
+++ b/doc/user/project/merge_requests/img/wip_mark_as_wip.png
diff --git a/doc/workflow/wip_merge_requests/unmark_as_wip.png b/doc/user/project/merge_requests/img/wip_unmark_as_wip.png
index 31f7326beb0..31f7326beb0 100644
--- a/doc/workflow/wip_merge_requests/unmark_as_wip.png
+++ b/doc/user/project/merge_requests/img/wip_unmark_as_wip.png
diff --git a/doc/user/project/merge_requests/merge_when_build_succeeds.md b/doc/user/project/merge_requests/merge_when_build_succeeds.md
new file mode 100644
index 00000000000..011f9cbc381
--- /dev/null
+++ b/doc/user/project/merge_requests/merge_when_build_succeeds.md
@@ -0,0 +1,46 @@
+# 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.
+
+![Enable](img/merge_when_build_succeeds_enable.png)
+
+When you hit the "Merge When Build Succeeds" button, the status of the merge
+request will be updated to represent the impending merge. If you cannot wait
+for the build to succeed and want to merge immediately, this option is available
+in the dropdown menu on the right of the main button.
+
+Both team developers and the author of the merge request have the option to
+cancel the automatic merge if they find a reason why it shouldn't be merged
+after all.
+
+![Status](img/merge_when_build_succeeds_status.png)
+
+When the build succeeds, the merge request will automatically be merged. When
+the build fails, the author gets a chance to retry any failed builds, or to
+push new commits to fix the failure.
+
+When the builds are retried and succeed on the second try, the merge request
+will automatically be merged after all. When the merge request is updated with
+new commits, the automatic merge is automatically canceled to allow the new
+changes to be reviewed.
+
+## Only allow merge requests to be merged if the build succeeds
+
+> **Note:**
+You need to have builds configured to enable this feature.
+
+You can prevent merge requests from being merged if their build did not succeed.
+
+Navigate to your project's settings page, select the
+**Only allow merge requests to be merged if the build succeeds** check box and
+hit **Save** for the changes to take effect.
+
+![Only allow merge if build succeeds settings](img/merge_when_build_succeeds_only_if_succeeds_settings.png)
+
+From now on, every time the build fails you will not be able to merge the merge
+request from the UI, until you make the build pass.
+
+![Only allow merge if build succeeds msg](img/merge_when_build_succeeds_only_if_succeeds_msg.png)
diff --git a/doc/user/project/merge_requests/revert_changes.md b/doc/user/project/merge_requests/revert_changes.md
new file mode 100644
index 00000000000..5ead9f4177f
--- /dev/null
+++ b/doc/user/project/merge_requests/revert_changes.md
@@ -0,0 +1,64 @@
+# Reverting changes
+
+> [Introduced][ce-1990] in GitLab 8.5.
+
+---
+
+GitLab implements Git's powerful feature to [revert any commit][git-revert]
+with introducing a **Revert** button in Merge Requests and commit details.
+
+## Reverting a Merge Request
+
+_**Note:** The **Revert** button will only be available for Merge Requests
+created since GitLab 8.5. However, you can still revert a Merge Request
+by reverting the merge commit from the list of Commits page._
+
+After the Merge Request has been merged, a **Revert** button will be available
+to revert the changes introduced by that Merge Request:
+
+![Revert Merge Request](img/revert_changes_mr.png)
+
+---
+
+You can revert the changes directly into the selected branch or you can opt to
+create a new Merge Request with the revert changes:
+
+![Revert Merge Request modal](img/revert_changes_mr_modal.png)
+
+---
+
+After the Merge Request has been reverted, the **Revert** button will not be
+available anymore.
+
+## Reverting a Commit
+
+You can revert a Commit from the Commit details page:
+
+![Revert commit](img/revert_changes_commit.png)
+
+---
+
+Similar to reverting a Merge Request, you can opt to revert the changes
+directly into the target branch or create a new Merge Request to revert the
+changes:
+
+![Revert commit modal](img/revert_changes_commit_modal.png)
+
+---
+
+After the Commit has been reverted, the **Revert** button will not be available
+anymore.
+
+Please note that when reverting merge commits, the mainline will always be the
+first parent. If you want to use a different mainline then you need to do that
+from the command line.
+
+Here is a quick example to revert a merge commit using the second parent as the
+mainline:
+
+```bash
+git revert -m 2 7a39eb0
+```
+
+[ce-1990]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/1990 "Revert button Merge Request"
+[git-revert]: https://git-scm.com/docs/git-revert "Git revert documentation"
diff --git a/doc/user/project/merge_requests/versions.md b/doc/user/project/merge_requests/versions.md
new file mode 100644
index 00000000000..2b1c5ddd562
--- /dev/null
+++ b/doc/user/project/merge_requests/versions.md
@@ -0,0 +1,22 @@
+# Merge requests versions
+
+> Will be [introduced][ce-5467] in GitLab 8.12.
+
+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.
+
+By default, the latest version of changes is shown. However, you
+can select an older one from version dropdown.
+
+![Merge Request Versions](img/versions.png)
+
+---
+
+>**Note:**
+Merge request versions are based on push not on commit. So, if you pushed 5
+commits in a single push, it will be a single option in the dropdown. If you
+pushed 5 times, that will count for 5 options.
+
+[ce-5467]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5467
diff --git a/doc/user/project/merge_requests/work_in_progress_merge_requests.md b/doc/user/project/merge_requests/work_in_progress_merge_requests.md
new file mode 100644
index 00000000000..546c8bdc5e5
--- /dev/null
+++ b/doc/user/project/merge_requests/work_in_progress_merge_requests.md
@@ -0,0 +1,17 @@
+# "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 a **Work In Progress**.
+
+![Blocked Accept Button](img/wip_blocked_accept_button.png)
+
+To mark a merge request a Work In Progress, simply start its title with `[WIP]`
+or `WIP:`.
+
+![Mark as WIP](img/wip_mark_as_wip.png)
+
+To allow a Work In Progress merge request to be accepted again when it's ready,
+simply remove the `WIP` prefix.
+
+![Unark as WIP](img/wip_unmark_as_wip.png)
diff --git a/doc/workflow/README.md b/doc/workflow/README.md
index fe13bd757c5..dcb9c32ad58 100644
--- a/doc/workflow/README.md
+++ b/doc/workflow/README.md
@@ -1,6 +1,5 @@
 # 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)
@@ -21,11 +20,15 @@
 - [Web Editor](../user/project/repository/web_editor.md)
 - [Releases](releases.md)
 - [Milestones](milestones.md)
-- [Merge Requests](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)
+- [Merge Requests](../user/project/merge_requests.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)
diff --git a/doc/workflow/authorization_for_merge_requests.md b/doc/workflow/authorization_for_merge_requests.md
index d1d6d94ec11..7bf80a3ad0d 100644
--- a/doc/workflow/authorization_for_merge_requests.md
+++ b/doc/workflow/authorization_for_merge_requests.md
@@ -1,40 +1 @@
-# Authorization for Merge requests
-
-There are two main ways to have a merge request flow with GitLab: working with protected branches in a single repository, or working with forks of an authoritative project.
-
-## Protected branch flow
-
-With the protected branch flow everybody works within the same GitLab project.
-
-The project maintainers get Master access and the regular developers get Developer access.
-
-The maintainers mark the authoritative branches as 'Protected'.
-
-The developers push feature branches to the project and create merge requests to have their feature branches reviewed and merged into one of the protected branches.
-
-Only users with Master access can merge changes into a protected branch.
-
-### Advantages
-
-- fewer projects means less clutter
-- developers need to consider only one remote repository
-
-### Disadvantages
-
-- manual setup of protected branch required for each new project
-
-## Forking workflow
-
-With the forking workflow the maintainers get Master access and the regular developers get Reporter access to the authoritative repository, which prohibits them from pushing any changes to it.
-
-Developers create forks of the authoritative project and push their feature branches to their own forks.
-
-To get their changes into master they need to create a merge request across forks.
-
-### Advantages
-
-- in an appropriately configured GitLab group, new projects automatically get the required access restrictions for regular developers: fewer manual steps to configure authorization for new projects
-
-### Disadvantages
-
-- the project need to keep their forks up to date, which requires more advanced Git skills (managing multiple remotes)
+This document was moved to [user/project/merge_requests/authorization_for_merge_requests](../user/project/merge_requests/authorization_for_merge_requests.md)
diff --git a/doc/workflow/cherry_pick_changes.md b/doc/workflow/cherry_pick_changes.md
index 64b94d81024..663ffd3f746 100644
--- a/doc/workflow/cherry_pick_changes.md
+++ b/doc/workflow/cherry_pick_changes.md
@@ -1,52 +1 @@
-# Cherry-pick changes
-
-> [Introduced][ce-3514] in GitLab 8.7.
-
----
-
-GitLab implements Git's powerful feature to [cherry-pick any commit][git-cherry-pick]
-with introducing a **Cherry-pick** button in Merge Requests and commit details.
-
-## Cherry-picking a Merge Request
-
-After the Merge Request has been merged, a **Cherry-pick** button will be available
-to cherry-pick the changes introduced by that Merge Request:
-
-![Cherry-pick Merge Request](img/cherry_pick_changes_mr.png)
-
----
-
-You can cherry-pick the changes directly into the selected branch or you can opt to
-create a new Merge Request with the cherry-pick changes:
-
-![Cherry-pick Merge Request modal](img/cherry_pick_changes_mr_modal.png)
-
-## Cherry-picking a Commit
-
-You can cherry-pick a Commit from the Commit details page:
-
-![Cherry-pick commit](img/cherry_pick_changes_commit.png)
-
----
-
-Similar to cherry-picking a Merge Request, you can opt to cherry-pick the changes
-directly into the target branch or create a new Merge Request to cherry-pick the
-changes:
-
-![Cherry-pick commit modal](img/cherry_pick_changes_commit_modal.png)
-
----
-
-Please note that when cherry-picking merge commits, the mainline will always be the
-first parent. If you want to use a different mainline then you need to do that
-from the command line.
-
-Here is a quick example to cherry-pick a merge commit using the second parent as the
-mainline:
-
-```bash
-git cherry-pick -m 2 7a39eb0
-```
-
-[ce-3514]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/3514 "Cherry-pick button Merge Request"
-[git-cherry-pick]: https://git-scm.com/docs/git-cherry-pick "Git cherry-pick documentation"
+This document was moved to [user/project/merge_requests/cherry_pick_changes](../user/project/merge_requests/cherry_pick_changes.md).
diff --git a/doc/workflow/merge_requests.md b/doc/workflow/merge_requests.md
index 40a5e4476be..a68bb8b27ca 100644
--- a/doc/workflow/merge_requests.md
+++ b/doc/workflow/merge_requests.md
@@ -1,90 +1 @@
-# Merge Requests
-
-Merge requests allow you to exchange changes you made to source code
-
-## Only allow merge requests to be merged if the build succeeds
-
-You can prevent merge requests from being merged if their build did not succeed
-in the project settings page.
-
-![only_allow_merge_if_build_succeeds](merge_requests/only_allow_merge_if_build_succeeds.png)
-
-Navigate to project settings page and select the `Only allow merge requests to be merged if the build succeeds` check box.
-
-Please note that you need to have builds configured to enable this feature.
-
-## Checkout merge requests locally
-
-### By adding a git alias
-
-Add the following alias to your `~/.gitconfig`:
-
-```
-[alias]
-    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:
-
-```
-$ git mr upstream 5
-```
-
-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
-
-Locate the section for your GitLab remote in the `.git/config` file. It looks like this:
-
-```
-[remote "origin"]
-  url = https://gitlab.com/gitlab-org/gitlab-ce.git
-  fetch = +refs/heads/*:refs/remotes/origin/*
-```
-
-Now add the line `fetch = +refs/merge-requests/*/head:refs/remotes/origin/merge-requests/*` to this section.
-
-It should look like this:
-
-```
-[remote "origin"]
-  url = https://gitlab.com/gitlab-org/gitlab-ce.git
-  fetch = +refs/heads/*:refs/remotes/origin/*
-  fetch = +refs/merge-requests/*/head:refs/remotes/origin/merge-requests/*
-```
-
-Now you can fetch all the merge requests:
-
-```
-$ 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:
-
-```
-$ git checkout origin/merge-requests/1
-```
-
-## Ignore whitespace changes in Merge Request diff view
-
-![MR diff](merge_requests/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/merge_request_diff_without_whitespace.png)
-
-It is also working on commits compare view.
-
-![Commit Compare](merge_requests/commit_compare.png)
-
-## Merge Requests versions
-
-Every time you push to merge request branch, a new version of merge request diff
-is created. When you visit the merge request page you see latest version of changes.
-However you can select an older one from version dropdown
-
-![Merge Request Versions](merge_requests/versions.png)
+This document was moved to [user/project/merge_requests](../user/project/merge_requests.md).
diff --git a/doc/workflow/merge_requests/merge_request_diff.png b/doc/workflow/merge_requests/merge_request_diff.png
deleted file mode 100644
index 3ebbfb75ea3..00000000000
--- a/doc/workflow/merge_requests/merge_request_diff.png
+++ /dev/null
diff --git a/doc/workflow/merge_requests/merge_request_diff_without_whitespace.png b/doc/workflow/merge_requests/merge_request_diff_without_whitespace.png
deleted file mode 100644
index a0db535019c..00000000000
--- a/doc/workflow/merge_requests/merge_request_diff_without_whitespace.png
+++ /dev/null
diff --git a/doc/workflow/merge_requests/versions.png b/doc/workflow/merge_requests/versions.png
deleted file mode 100644
index c0a6dfe6806..00000000000
--- a/doc/workflow/merge_requests/versions.png
+++ /dev/null
diff --git a/doc/workflow/merge_when_build_succeeds.md b/doc/workflow/merge_when_build_succeeds.md
index 75e1fdff2b2..95afd12ebdb 100644
--- a/doc/workflow/merge_when_build_succeeds.md
+++ b/doc/workflow/merge_when_build_succeeds.md
@@ -1,15 +1 @@
-# 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.
-
-![Enable](merge_when_build_succeeds/enable.png)
-
-When you hit the "Merge When Build Succeeds" button, the status of the merge request will be updated to represent the impending merge. If you cannot wait for the build to succeed and want to merge immediately, this option is available in the dropdown menu on the right of the main button.
-
-Both team developers and the author of the merge request have the option to cancel the automatic merge if they find a reason why it shouldn't be merged after all.
-
-![Status](merge_when_build_succeeds/status.png)
-
-When the build succeeds, the merge request will automatically be merged. When the build fails, the author gets a chance to retry any failed builds, or to push new commits to fix the failure.
-
-When the builds are retried and succeed on the second try, the merge request will automatically be merged after all. When the merge request is updated with new commits, the automatic merge is automatically canceled to allow the new changes to be reviewed.
+This document was moved to [user/project/merge_requests/merge_when_build_succeeds](../user/project/merge_requests/merge_when_build_succeeds.md).
diff --git a/doc/workflow/revert_changes.md b/doc/workflow/revert_changes.md
index 5ead9f4177f..cf1292253fc 100644
--- a/doc/workflow/revert_changes.md
+++ b/doc/workflow/revert_changes.md
@@ -1,64 +1 @@
-# Reverting changes
-
-> [Introduced][ce-1990] in GitLab 8.5.
-
----
-
-GitLab implements Git's powerful feature to [revert any commit][git-revert]
-with introducing a **Revert** button in Merge Requests and commit details.
-
-## Reverting a Merge Request
-
-_**Note:** The **Revert** button will only be available for Merge Requests
-created since GitLab 8.5. However, you can still revert a Merge Request
-by reverting the merge commit from the list of Commits page._
-
-After the Merge Request has been merged, a **Revert** button will be available
-to revert the changes introduced by that Merge Request:
-
-![Revert Merge Request](img/revert_changes_mr.png)
-
----
-
-You can revert the changes directly into the selected branch or you can opt to
-create a new Merge Request with the revert changes:
-
-![Revert Merge Request modal](img/revert_changes_mr_modal.png)
-
----
-
-After the Merge Request has been reverted, the **Revert** button will not be
-available anymore.
-
-## Reverting a Commit
-
-You can revert a Commit from the Commit details page:
-
-![Revert commit](img/revert_changes_commit.png)
-
----
-
-Similar to reverting a Merge Request, you can opt to revert the changes
-directly into the target branch or create a new Merge Request to revert the
-changes:
-
-![Revert commit modal](img/revert_changes_commit_modal.png)
-
----
-
-After the Commit has been reverted, the **Revert** button will not be available
-anymore.
-
-Please note that when reverting merge commits, the mainline will always be the
-first parent. If you want to use a different mainline then you need to do that
-from the command line.
-
-Here is a quick example to revert a merge commit using the second parent as the
-mainline:
-
-```bash
-git revert -m 2 7a39eb0
-```
-
-[ce-1990]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/1990 "Revert button Merge Request"
-[git-revert]: https://git-scm.com/docs/git-revert "Git revert documentation"
+This document was moved to [user/project/merge_requests/revert_changes](../user/project/merge_requests/revert_changes.md).
diff --git a/doc/workflow/wip_merge_requests.md b/doc/workflow/wip_merge_requests.md
index 46035a5e6b6..abb8002f442 100644
--- a/doc/workflow/wip_merge_requests.md
+++ b/doc/workflow/wip_merge_requests.md
@@ -1,13 +1 @@
-# "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 a **Work In Progress**.
-
-![Blocked Accept Button](wip_merge_requests/blocked_accept_button.png)
-
-To mark a merge request a Work In Progress, simply start its title with `[WIP]` or `WIP:`.
-
-![Mark as WIP](wip_merge_requests/mark_as_wip.png)
-
-To allow a Work In Progress merge request to be accepted again when it's ready, simply remove the `WIP` prefix.
-
-![Unark as WIP](wip_merge_requests/unmark_as_wip.png)
+This document was moved to [user/project/merge_requests/work_in_progress_merge_requests](../user/project/merge_requests/work_in_progress_merge_requests.md).