diff options
Diffstat (limited to 'doc/user/discussions/index.md')
| -rw-r--r-- | doc/user/discussions/index.md | 161 |
1 files changed, 135 insertions, 26 deletions
diff --git a/doc/user/discussions/index.md b/doc/user/discussions/index.md index 1e2fad1efe9..5d69efc3600 100644 --- a/doc/user/discussions/index.md +++ b/doc/user/discussions/index.md @@ -5,36 +5,42 @@ The ability to contribute conversationally is offered throughout GitLab. You can leave a comment in the following places: - issues +- epics **[ULTIMATE]** - merge requests - snippets - commits - commit diffs -The comment area supports [Markdown] and [quick actions]. One can edit their -own comment at any time, and anyone with [Maintainer access level][permissions] or -higher can also edit a comment made by someone else. +There are standard comments, and you also have the option to create a comment +in the form of a threaded discussion. A comment can also be [turned into a discussion](#start-a-discussion-by-replying-to-a-standard-comment) +when it receives a reply. -You could also reply to the notification email in order to reply to a comment, -provided that [Reply by email] is configured by your GitLab admin. This also -supports [Markdown] and [quick actions] as if replied from the web. +The comment area supports [Markdown] and [quick actions]. You can edit your own +comment at any time, and anyone with [Maintainer access level][permissions] or +higher can also edit a comment made by someone else. -Apart from the standard comments, you also have the option to create a comment -in the form of a resolvable or threaded discussion. +You can also reply to a comment notification email to reply to the comment if +[Reply by email] is configured for your GitLab instance. Replying to a standard comment +creates another standard comment. Replying to a discussion comment creates a reply in the +discussion thread. Email replies support [Markdown] and [quick actions], just as if you replied from the web. -## Resolvable discussions +## Resolvable comments and discussions > **Notes:** +> > - The main feature was [introduced][ce-5022] in GitLab 8.11. > - Resolvable discussions can be added only to merge request diffs. Discussion resolution helps keep track of progress during planning or code review. -Resolving comments prevents you from forgetting to address feedback and lets you -hide discussions that are no longer relevant. -!["A discussion between two people on a piece of code"][discussion-view] +Every standard comment or discussion thread in merge requests, commits, commit diffs, and +snippets is initially displayed as unresolved. They can then be individually resolved by anyone +with at least Developer access to the project or by the author of the change being reviewed. -Comments and discussions can be resolved by anyone with at least Developer -access to the project or the author of the merge request. +The need to resolve all standard comments or discussions prevents you from forgetting +to address feedback and lets you hide discussions that are no longer relevant. + +!["A discussion between two people on a piece of code"][discussion-view] ### Commit discussions in the context of a merge request @@ -272,7 +278,76 @@ edit existing comments. Non-team members are restricted from adding or editing c | :-----------: | :----------: | |  |  | -Additionally locked issues can not be reopened. +Additionally, locked issues and merge requests can not be reopened. + +## Merge Request Reviews **[PREMIUM]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/4213) in GitLab 11.4. + +When looking at a Merge Request diff, you are able to start a review. +This allows you to create comments inside a Merge Request that are **only visible to you** until published, +in order to allow you to submit them all as a single action. + +### Starting a review + +In order to start a review, simply write a comment on a diff as normal under the **Changes** tab +in an MR and click on the **Start a review** button. + + + +Once a review is started, you will see any comments that are part of this review marked `Pending`. +All comments that are part of a review show two buttons: + +- **Submit review**: Submits all comments that are part of the review, making them visible to other users. +- **Add comment now**: Submits the specific comment as a regular comment instead of as part of the review. + + + +You can use [quick actions] inside review comments. The comment will show the actions that will be performed once published. + + + +To add more comments to a review, start writing a comment as normal and click the **Add to review** button. + + + +This will add the comment to the review. + + + +### Resolving/Unresolving discussions + +Review comments can also resolve/unresolve [resolvable discussions](#resolvable-comments-and-discussions). +When replying to a comment, you will see a checkbox that you can click in order to resolve or unresolve +the discussion once published. + + + + +If a particular pending comment will resolve or unresolve the discussion, this will be shown on the pending +comment itself. + + + + +### Submitting a review + +If you have any comments that have not been submitted, you will see a bar at the +bottom of the screen with two buttons: + +- **Discard**: Discards all comments that have not been submitted. +- **Finish review**: Opens a list of comments ready to be submitted for review. + Clicking **Submit review** will publish all comments. Any quick actions + submitted are performed at this time. + +Alternatively, every pending comment has a button to finish the entire review. + + + +Submitting the review will send a single email to every notifiable user of the +merge request with all the comments associated to it. + +Replying to this email will, consequentially, create a new comment on the associated merge request. ## Filtering notes @@ -310,11 +385,6 @@ the Merge Request authored by the user that applied them.  - > **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:  @@ -326,19 +396,58 @@ the Merge Request authored by the user that applied them.  - > **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. +the discussion will be automatically resolved, 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). +### Multi-line suggestions + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/53310) in GitLab 11.10. + +Reviewers can also suggest changes to multiple lines with a single suggestion +within Merge Request diff discussions by adjusting the range offsets. The +offsets are relative to the position of the diff discussion, and specify the +range to be replaced by the suggestion when it is applied. + + + +In the example above, the suggestion covers three lines above and four lines +below the commented line. When applied, it would replace from 3 lines _above_ +to 4 lines _below_ the commented line, with the suggested change. + + + +NOTE: **Note:** +Suggestions covering multiple lines are limited to 100 lines _above_ and 100 +lines _below_ the commented diff line, allowing up to 200 changed lines per +suggestion. + +## Start a discussion by replying to a standard comment + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/30299) in GitLab 11.9 + +To reply to a standard (non-discussion) comment, you can use the **Reply to comment** button. + + + +The **Reply to comment** button is only displayed if you have permissions to reply to an existing discussion, or start a discussion from a standard comment. + +Clicking on the **Reply to comment** button will bring the reply area into focus and you can type your reply. + + + +Relying to a non-discussion comment will convert the non-discussion comment to a +threaded discussion once the reply is submitted. This conversion is considered an edit +to the original comment, so a note about when it was last edited will appear underneath it. + +This feature only exists for Issues, Merge requests, and Epics. Commits, Snippets and Merge request diff discussions are not supported yet. + [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 |