Add 'squash and rebase' feature to CE

7 files changed, 93 insertions, 3 deletions

diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md
index 4e34831422a..8849f490c4f 100644
--- a/doc/api/merge_requests.md
+++ b/doc/api/merge_requests.md
@@ -107,6 +107,7 @@ Parameters:
     "changes_count": "1",
     "should_remove_source_branch": true,
     "force_remove_source_branch": false,
+    "squash": false,
     "web_url": "http://example.com/example/example/merge_requests/1",
     "time_stats": {
       "time_estimate": 0,
@@ -226,6 +227,7 @@ Parameters:
     "changes_count": "1",
     "should_remove_source_branch": true,
     "force_remove_source_branch": false,
+    "squash": false,
     "web_url": "http://example.com/example/example/merge_requests/1",
     "discussion_locked": false,
     "time_stats": {
@@ -305,6 +307,7 @@ Parameters:
   "changes_count": "1",
   "should_remove_source_branch": true,
   "force_remove_source_branch": false,
+  "squash": false,
   "web_url": "http://example.com/example/example/merge_requests/1",
   "discussion_locked": false,
   "time_stats": {
@@ -541,7 +544,8 @@ POST /projects/:id/merge_requests
 | `labels`                   | string  | no       | Labels for MR as a comma-separated list                                         |
 | `milestone_id`             | integer | no       | The global ID of a milestone                                                           |
 | `remove_source_branch`     | boolean | no       | Flag indicating if a merge request should remove the source branch when merging |
-| `allow_maintainer_to_push` | boolean | no       | Whether or not a maintainer of the target project can push to the source branch  |
+| `allow_maintainer_to_push` | boolean | no       | Whether or not a maintainer of the target project can push to the source branch |
+| `squash`                   | boolean | no       | Squash commits into a single commit when merging                                |
 
 ```json
 {
@@ -595,6 +599,7 @@ POST /projects/:id/merge_requests
   "changes_count": "1",
   "should_remove_source_branch": true,
   "force_remove_source_branch": false,
+  "squash": false,
   "web_url": "http://example.com/example/example/merge_requests/1",
   "discussion_locked": false,
   "allow_maintainer_to_push": false,
@@ -627,6 +632,7 @@ PUT /projects/:id/merge_requests/:merge_request_iid
 | `description`              | string  | no       | Description of MR                                                               |
 | `state_event`              | string  | no       | New state (close/reopen)                                                        |
 | `remove_source_branch`     | boolean | no       | Flag indicating if a merge request should remove the source branch when merging |
+| `squash`                   | boolean | no       | Squash commits into a single commit when merging |
 | `discussion_locked`        | boolean | no       | Flag indicating if the merge request's discussion is locked. If the discussion is locked only project members can add, edit or resolve comments. |
 | `allow_maintainer_to_push` | boolean | no       | Whether or not a maintainer of the target project can push to the source branch |
 
@@ -683,6 +689,7 @@ Must include at least one non-required attribute from above.
   "changes_count": "1",
   "should_remove_source_branch": true,
   "force_remove_source_branch": false,
+  "squash": false,
   "web_url": "http://example.com/example/example/merge_requests/1",
   "discussion_locked": false,
   "allow_maintainer_to_push": false,
@@ -790,6 +797,7 @@ Parameters:
   "changes_count": "1",
   "should_remove_source_branch": true,
   "force_remove_source_branch": false,
+  "squash": false,
   "web_url": "http://example.com/example/example/merge_requests/1",
   "discussion_locked": false,
   "time_stats": {
@@ -868,6 +876,7 @@ Parameters:
   "changes_count": "1",
   "should_remove_source_branch": true,
   "force_remove_source_branch": false,
+  "squash": false,
   "web_url": "http://example.com/example/example/merge_requests/1",
   "discussion_locked": false,
   "time_stats": {
@@ -1200,6 +1209,7 @@ Example response:
     "changes_count": "1",
     "should_remove_source_branch": true,
     "force_remove_source_branch": false,
+    "squash": false,
     "web_url": "http://example.com/example/example/merge_requests/1"
   },
   "target_url": "https://gitlab.example.com/gitlab-org/gitlab-ci/merge_requests/7",
diff --git a/doc/user/project/merge_requests/img/squash_edit_form.png b/doc/user/project/merge_requests/img/squash_edit_form.png
new file mode 100644
index 00000000000..496c6f44ea7
--- /dev/null
+++ b/doc/user/project/merge_requests/img/squash_edit_form.png
diff --git a/doc/user/project/merge_requests/img/squash_mr_commits.png b/doc/user/project/merge_requests/img/squash_mr_commits.png
new file mode 100644
index 00000000000..5fc6a8c48bb
--- /dev/null
+++ b/doc/user/project/merge_requests/img/squash_mr_commits.png
diff --git a/doc/user/project/merge_requests/img/squash_mr_widget.png b/doc/user/project/merge_requests/img/squash_mr_widget.png
new file mode 100644
index 00000000000..9cb458b2a35
--- /dev/null
+++ b/doc/user/project/merge_requests/img/squash_mr_widget.png
diff --git a/doc/user/project/merge_requests/img/squash_squashed_commit.png b/doc/user/project/merge_requests/img/squash_squashed_commit.png
new file mode 100644
index 00000000000..0cf5875f82c
--- /dev/null
+++ b/doc/user/project/merge_requests/img/squash_squashed_commit.png
diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md
index 5932f5a2bc1..b75bcacc9d7 100644
--- a/doc/user/project/merge_requests/index.md
+++ b/doc/user/project/merge_requests/index.md
@@ -29,12 +29,12 @@ With GitLab merge requests, you can:
 - 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
 - [Create new merge requests by email](#create-new-merge-requests-by-email)
 - Allow maintainers of the target project to push directly to the fork by [allowing edits from maintainers](maintainer_access.md)
+- [Squash and merge](squash_and_merge.md) for a cleaner commit history
 
 With **[GitLab Enterprise Edition][ee]**, you can also:
 
 - View the deployment process across projects with [Multi-Project Pipeline Graphs](https://docs.gitlab.com/ee/ci/multi_project_pipeline_graphs.html#multi-project-pipeline-graphs) **[PREMIUM]**
 - Request [approvals](https://docs.gitlab.com/ee/user/project/merge_requests/merge_request_approvals.html) from your managers **[STARTER]**
-- [Squash and merge](https://docs.gitlab.com/ee/user/project/merge_requests/squash_and_merge.html) for a cleaner commit history **[STARTER]**
 - Analyze the impact of your changes with [Code Quality reports](https://docs.gitlab.com/ee/user/project/merge_requests/code_quality_diff.html) **[STARTER]**
 
 ## Use cases
@@ -57,7 +57,7 @@ B. Consider you're a web developer writing a webpage for your company's:
 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](https://docs.gitlab.com/ee/user/project/merge_requests/merge_request_approvals.html) from your manager **[STARTER]**
-1. Once approved, your merge request is [squashed and merged](https://docs.gitlab.com/ee/user/project/merge_requests/squash_and_merge.html), and [deployed to staging with GitLab Pages](https://about.gitlab.com/2016/08/26/ci-deployment-and-environments/) (Squash and Merge is available in GitLab Starter)
+1. Once approved, your merge request is [squashed and merged](squash_and_merge.md), 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
 
 ## Merge requests per project
diff --git a/doc/user/project/merge_requests/squash_and_merge.md b/doc/user/project/merge_requests/squash_and_merge.md
new file mode 100644
index 00000000000..a6efe893853
--- /dev/null
+++ b/doc/user/project/merge_requests/squash_and_merge.md
@@ -0,0 +1,80 @@
+# Squash and merge
+
+> [Introduced][ee-1024] in [GitLab Starter][ee] 8.17, and in [GitLab CE][ce] [11.0][ce-18956].
+
+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,
+and then merges that commit using the merge method set for the project.
+
+In other words, squashing a merge request turns a long list of commits:
+
+![List of commits from a merge request][mr-commits]
+
+Into a single commit on merge:
+
+![A squashed commit followed by a merge commit][squashed-commit]
+
+The squashed commit's commit message is the merge request title. And 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
+[squashing and fast-forward merge](#squash-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
+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]
+
+## Commit metadata for squashed commits
+
+The squashed commit has the following metadata:
+
+* Message: the title of the merge request.
+* Author: the author of the merge request.
+* Committer: the user who initiated the squash.
+
+## Squash and fast-forward merge
+
+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
+[ce-18956]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/18956
+[mr-commits]: img/squash_mr_commits.png
+[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#enabling-fast-forward-merges
+[ce]: https://about.gitlab.com/products/
+[ee]: https://about.gitlab.com/products/
+[revert]: revert_changes.md