Merge branch 'docs/ff-mr' into 'master'

Add use cases for squash and fast forward MR docs

Closes #2814

See merge request !2384

doc/user/project/merge_requests/fast_forward_merge.md

@@ -2,13 +2,27 @@
 
 > Included in [GitLab Enterprise Edition Starter][products].
 
-If you prefer a linear Git history and a way to accept merge requests without
-creating merge commits, you can configure this on a per-project basis.
+Retain a linear Git history and a way to accept merge requests without
+creating merge commits.
 
-Navigate to the project's settings, select the **Fast-forward merge**
-option and hit **Save changes** for the changes to take effect.
+## Overview
 
-![Fast forward merge in project settings](img/ff_merge.png)
+When the fast-forward merge ([`--ff-only`][ffonly]) setting is enabled, no merge
+commits will be created and all merges are fast-forwarded, which means that
+merging is only allowed if the branch could be fast-forwarded.
+
+When a fast-forward merge is not possible, the user is given the option to rebase.
+
+## Use cases
+
+Sometimes, a workflow policy might mandate a clean commit history without
+merge commits. In such cases, the fast-forward merge is the perfect candidate.
+
+## Enabling fast-forward merges
+
+1. Navigate to your project's **Settings** and search for the 'Merge method'
+1. Select the **Fast-forward merge** option
+1. Hit **Save changes** for the changes to take effect
 
 Now, when you visit the merge request page, you will be able to accept it
 **only if a fast-forward merge is possible**.
@@ -18,4 +32,7 @@ Now, when you visit the merge request page, you will be able to accept it
 If the target branch is ahead of the source branch, you need to rebase the
 source branch before you will be able to do a fast-forward merge.
 
+![Fast forward merge rebase](img/ff_merge_rebase.png)
+
 [products]: https://about.gitlab.com/products/ "GitLab products page"
+[ffonly]: https://git-scm.com/docs/git-merge#git-merge---ff-only

doc/user/project/merge_requests/squash_and_merge.md

 # Squash and merge
 
-> [Introduced][ee-1024] in GitLab Enterprise Edition 8.17.
+> [Introduced][ee-1024] in [GitLab Enterprise Edition Starter][ee] 8.17.
+
+Combine all commits of your merge request into one and retain a clean history.
+
+## Overview
 
 Squashing lets you tidy up the commit history of a branch when accepting a merge
 request. It applies all of the changes in the merge request as a single commit,
@@ -16,10 +20,24 @@ Into a single commit on merge:
 
 Note that the squashed commit is still followed by a merge commit, as the merge
 method for this example repository uses a merge commit. Squashing also works
-with the fast-forward merge strategy: see
+with the fast-forward merge strategy, see
 [squashing and fast-forward merge](#squashing-and-fast-forward-merge) for more
 details.
 
+## Use cases
+
+When working on a feature branch, you sometimes want to commit your current
+progress, but don't really care about the commit messages. Those 'work in
+progress commits' don't necessarily contain important information and as such
+you'd rather not include them in your target branch. 
+
+With squash and merge, when the merge request is ready to be merged,
+all you have to do is enable squashing before you press merge to join
+the commits include in the merge request into a single commit.
+
+This way, the history of your base branch remains clean with
+meaningful commit messages and is simpler to [revert] if necessary.
+
 ## Enabling squash for a merge request
 
 Anyone who can create or edit a merge request can choose for it to be squashed
@@ -27,6 +45,8 @@ on the merge request form:
 
 ![Squash commits checkbox on edit form][squash-edit-form]
 
+---
+
 This can then be overridden at the time of accepting the merge request:
 
 ![Squash commits checkbox on accept merge request form][squash-mr-widget]
@@ -39,12 +59,12 @@ The squashed commit has the following metadata:
 * Author: the author of the merge request.
 * Committer: the user who initiated the squash.
 
-## Squashing and [fast-forward merge][ff-merge]
+## Squash and fast-forward merge
 
-When a project has the fast-forward merge setting enabled, the merge request
-must be able to be fast-forwarded without squashing in order to squash it. This
-is because squashing is only available when accepting a merge request, so a
-merge request may need to be [rebased][rebase] before squashing, even though
+When a project has the [fast-forward merge setting enabled][ff-merge], the merge
+request must be able to be fast-forwarded without squashing in order to squash
+it. This is because squashing is only available when accepting a merge request,
+so a merge request may need to be rebased before squashing, even though
 squashing can itself be considered equivalent to rebasing.
 
 [ee-1024]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/1024
@@ -52,5 +72,6 @@ squashing can itself be considered equivalent to rebasing.
 [squashed-commit]: img/squash_squashed_commit.png
 [squash-edit-form]: img/squash_edit_form.png
 [squash-mr-widget]: img/squash_mr_widget.png
-[ff-merge]: fast_forward_merge.md
-[rebase]: ../../../workflow/rebase_before_merge.md
+[ff-merge]: fast_forward_merge.md#enabling-fast-forward-merges
+[ee]: https://about.gitlab.com/gitlab-ee/
+[revert]: revert_changes.md

doc/workflow/gitlab_flow.md

@@ -187,7 +187,7 @@ If you have an issue that spans across multiple repositories, the best thing is
 ![Vim screen showing the rebase view](rebase.png)
 
 With git you can use an interactive rebase (`rebase -i`) to squash multiple commits into one and reorder them.
-In GitLab EE and .com you can also [rebase before merge](http://docs.gitlab.com/ee/workflow/rebase_before_merge.html) from the web interface.
+In GitLab Enterprise Edition Starter and GitLab.com, you can also [rebase before merge](../user/project/merge_requests/fast_forward_merge.md) from the web interface.
 This functionality is useful if you made a couple of commits for small changes during development and want to replace them with a single commit or if you want to make the order more logical.
 However you should never rebase commits you have pushed to a remote server.
 Somebody can have referred to the commits or cherry-picked them.
@@ -324,4 +324,4 @@ Merging only when needed prevents creating merge commits in your feature branch
 ## References
 
 - [Git Flow by Vincent Driessen](http://nvie.com/posts/a-successful-git-branching-model/)
-- [Blog post with responses](https://about.gitlab.com/2014/09/29/gitlab-flow/)
\ No newline at end of file
+- [Blog post on GitLab flow](https://about.gitlab.com/2014/09/29/gitlab-flow/)

doc/workflow/rebase_before_merge.md

-# Rebase before merge
-
-GitLab Enterprise Edition offers a way to rebase the source branch of a merge request.
-This feature is part of the [Fast-forward merge](ff_merge.md) feature.
-It allows you to rebase the source branch of a merge request in order to perform a fast-forward merge.
-
-You can configure this on a per-project basis by navigating to the project settings page and selecting the **Rebase button** checkbox.
-This checkbox is visible only if you have the **Only fast-forward merging** checkbox enabled.
-
-![Merge request settings](merge_request_settings.png)
-
-
-Now, if a fast-forward merge requires a rebase, you will see a button to perform a rebase:
-
-![Rebase request widget](rebase_request_widget.png)
-
-GitLab will attempt to rebase the source branch. If the rebase succeeds you will see an **Accept merge request** button.
-If a clean rebase is not possible, you will need to rebase manually.
-Rebasing may require some conflicts to be resolved manually.
+This document was moved to [another location](../user/project/merge_requests/fast_forward_merge.md).