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 Binary files /dev/null and b/doc/user/discussions/img/insert_suggestion.png differ 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 Binary files /dev/null and b/doc/user/discussions/img/make_suggestion.png differ diff --git a/doc/user/discussions/img/suggestion.png b/doc/user/discussions/img/suggestion.png new file mode 100644 index 00000000000..68a67e6ae5e Binary files /dev/null and b/doc/user/discussions/img/suggestion.png differ 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 ` +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