Suggest diff line change documentation

7 files changed, 92 insertions, 0 deletions

diff --git a/doc/api/suggestions.md b/doc/api/suggestions.md
new file mode 100644
index 00000000000..9d76ef0c4bf
--- /dev/null
+++ b/doc/api/suggestions.md
@@ -0,0 +1,36 @@
+# Suggest Changes API
+
+Every API call to suggestions must be authenticated.
+
+## Applying suggestions
+
+Applies a suggested patch in a merge request. Users must be
+at least [Developer](../user/permissions.md) to perform such action.
+
+```
+PUT /suggestions/:id/apply
+```
+
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer/string | yes | The ID of a suggestion |
+
+```bash
+curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/suggestions/5/apply
+```
+
+Example response:
+
+```json
+  {
+    "id": 36,
+    "from_original_line": 10,
+    "to_original_line": 10,
+    "from_line": 10,
+    "to_line": 10,
+    "appliable": false,
+    "applied": true,
+    "from_content": "        \"--talk-name=org.freedesktop.\",\n",
+    "to_content": "        \"--talk-name=org.free.\",\n        \"--talk-name=org.desktop.\",\n"
+  }
+```
diff --git a/doc/user/discussions/img/insert_suggestion.png b/doc/user/discussions/img/insert_suggestion.png
new file mode 100644
index 00000000000..4bf293b8297
--- /dev/null
+++ b/doc/user/discussions/img/insert_suggestion.png
diff --git a/doc/user/discussions/img/make_suggestion.png b/doc/user/discussions/img/make_suggestion.png
new file mode 100644
index 00000000000..20acc1417da
--- /dev/null
+++ b/doc/user/discussions/img/make_suggestion.png
diff --git a/doc/user/discussions/img/suggestion.png b/doc/user/discussions/img/suggestion.png
new file mode 100644
index 00000000000..68a67e6ae5e
--- /dev/null
+++ b/doc/user/discussions/img/suggestion.png
diff --git a/doc/user/discussions/index.md b/doc/user/discussions/index.md
index 0f89d261ff6..9379d047fca 100644
--- a/doc/user/discussions/index.md
+++ b/doc/user/discussions/index.md
@@ -293,6 +293,51 @@ Once you select one of the filters in a given issue or MR, GitLab will save
 your preference, so that it will persist when you visit the same page again
 from any device you're logged into.
 
+## Suggest Changes
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/18008) in GitLab 11.6.
+
+As a reviewer, you're able to suggest code changes with a simple 
+markdown syntax in Merge Request Diff discussions. Then, the
+Merge Request author (or other users with appropriate 
+[permission](../permissions.md)) is able to apply these
+suggestions with a click, which will generate a commit in 
+the Merge Request authored by the user that applied them.
+
+1. Choose a line of code to be changed, add a new comment, then click
+on the **Insert suggestion** icon in the toolbar:
+
+    ![Add a new comment](img/insert_suggestion.png)
+    
+    > **Note:**
+    The suggestion will only affect the commented line. Multi-line
+    suggestions are currently not supported. Will be introduced by 
+    [#53310](https://gitlab.com/gitlab-org/gitlab-ce/issues/53310).
+
+1. In the comment, add your suggestion to the pre-populated code block:
+
+    ![Add a suggestion into a code block tagged properly](img/make_suggestion.png)
+
+1. Click **Comment**.
+
+    The suggestions in the comment can be applied by the merge request author
+    directly from the merge request:
+
+    ![Apply suggestions](img/suggestion.png)
+
+    > **Note:**
+    Discussions are _not_ automatically resolved. Will be introduced by 
+    [#54405](https://gitlab.com/gitlab-org/gitlab-ce/issues/54405).
+    
+Once the author applies a suggestion, it will be marked with the **Applied** label,
+and GitLab will create a new commit with the message `Apply suggestion to <file-name>`
+and push the suggested change directly into the codebase in the merge request's branch.
+[Developer permission](../permissions.md) is required to do so.
+
+> **Note:**
+Custom commit messages will be introduced by
+[#54404](https://gitlab.com/gitlab-org/gitlab-ce/issues/54404).
+
 [ce-5022]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5022
 [ce-7125]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7125
 [ce-7527]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7527
diff --git a/doc/user/permissions.md b/doc/user/permissions.md
index c4a2d5f66e5..ed00f86f9de 100644
--- a/doc/user/permissions.md
+++ b/doc/user/permissions.md
@@ -79,6 +79,7 @@ The following table depicts the various user permission levels in a project.
 | View approved/blacklisted licenses **[ULTIMATE]** |         |            | ✓           | ✓        | ✓      |
 | Use security dashboard **[ULTIMATE]** |         |            | ✓           | ✓        | ✓      |
 | Dismiss vulnerability **[ULTIMATE]**  |         |            | ✓           | ✓        | ✓      |
+| Apply code change suggestions         |         |            | ✓           | ✓        | ✓      |
 | Use environment terminals             |         |            |             | ✓        | ✓      |
 | Add new team members                  |         |            |             | ✓        | ✓      |
 | Push to protected branches            |         |            |             | ✓        | ✓      |
diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md
index 85d8d804133..d4f8cf929f6 100644
--- a/doc/user/project/merge_requests/index.md
+++ b/doc/user/project/merge_requests/index.md
@@ -150,6 +150,16 @@ in a Merge Request. To do so, click the **...** button in the gutter of the Merg
 
 ![Comment on any diff file line](img/comment-on-any-diff-line.png)
 
+## Suggest changes
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/18008) in GitLab 11.6.
+
+As a reviewer, you can add suggestions to change the content in
+merge request discussions, and users with appropriate [permission](../../permissions.md)
+can easily apply them to the codebase directly from the UI. Read
+through the documentation on [Suggest changes](../../discussions/index.md#suggest-changes)
+to learn more.
+
 ## Resolve conflicts
 
 When a merge request has conflicts, GitLab may provide the option to resolve