diff options
Diffstat (limited to 'doc/user/discussions/index.md')
| -rw-r--r-- | doc/user/discussions/index.md | 409 |
1 files changed, 180 insertions, 229 deletions
diff --git a/doc/user/discussions/index.md b/doc/user/discussions/index.md index cf57afb8324..825f9be6ba6 100644 --- a/doc/user/discussions/index.md +++ b/doc/user/discussions/index.md @@ -5,343 +5,294 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, howto --- -# Threads **(FREE)** +# Comments and threads **(FREE)** GitLab encourages communication through comments, threads, and [code suggestions](../project/merge_requests/reviews/suggestions.md). -For example, you can create a comment in the following places: +There are two types of comments: -- Issues -- Epics -- Merge requests -- Snippets -- Commits -- Commit diffs +- A standard comment. +- A comment in a thread, which has to be resolved. -There are standard comments, and you also have the option to create a comment -in the form of a thread. A comment can also be [turned into a thread](#start-a-thread-by-replying-to-a-standard-comment) -when it receives a reply. +In a comment, you can enter [Markdown](../markdown.md) and use [quick actions](../project/quick_actions.md). -The comment area supports [Markdown](../markdown.md) and [quick actions](../project/quick_actions.md). -You can [suggest code changes](../project/merge_requests/reviews/suggestions.md) in your comment, -which the user can accept through the user interface. You can edit your own -comment at any time, and anyone with the [Maintainer role](../permissions.md) or -higher can also edit a comment made by someone else. - -You can also reply to a comment notification email to reply to the comment if -[Reply by email](../../administration/reply_by_email.md) is configured for your GitLab instance. Replying to a standard comment -creates another standard comment. Replying to a threaded comment creates a reply in the thread. Email replies support -[Markdown](../markdown.md) and [quick actions](../project/quick_actions.md), just as if you replied from the web. +You can [suggest code changes](../project/merge_requests/reviews/suggestions.md) in your commit diff comment, +which the user can accept through the user interface. -NOTE: -There is a limit of 5,000 comments for every object, for example: issue, epic, and merge request. +## Places you can add comments -## Resolvable comments and threads +You can create comments in places like: -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5022) in GitLab 8.11. -> - Resolvable threads can be added only to merge request diffs. -> - Resolving comments individually was [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/28750) in GitLab 13.6. - -Thread resolution helps keep track of progress during planning or code review. - -Every 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. -If the thread has been resolved and a non-member un-resolves their own response, -this also unresolves the discussion thread. -If the non-member then resolves this same response, this resolves the discussion thread. - -The need to resolve threads prevents you from forgetting to address feedback and lets you -hide threads that are no longer relevant. - - - -### Commit threads in the context of a merge request - -For reviewers with commit-based workflow, it may be useful to add threads to -specific commit diffs in the context of a merge request. These threads -persist through a commit ID change when: - -- force-pushing after a rebase -- amending a commit +- Commit diffs +- Commits +- Designs +- Epics +- Issues +- Merge requests +- Snippets -To create a commit diff thread: +Each object can have as many as 5,000 comments. -1. Navigate to the merge request **Commits** tab. A list of commits that - constitute the merge request are shown. +## Add a comment to a merge request diff -  +You can add comments to a merge request diff. These comments +persist, even when you: -1. Navigate to a specific commit, select the **Changes** tab (where you - are only be presented diffs from the selected commit), and leave a comment. +- Force-push after a rebase. +- Amend a commit. -  +To add a commit diff comment: -1. Any threads created this way are shown in the merge request's - **Discussions** tab and are resolvable. +1. To select a specific commit, on the merge request, select the **Commits** tab, select the commit + message. To view the latest commit, select the **Changes** tab. +1. By the line you want to comment on, hover over the line number and select **{comment}**. + You can select multiple lines by dragging the **{comment}** icon. +1. Type your comment and select **Start a review** or **Add comment now**. -  +The comment is displayed on the merge request's **Discussions** tab. -Threads created this way only appear in the original merge request -and not when navigating to that commit under your project's -**Repository > Commits** page. +The comment is not displayed on your project's **Repository > Commits** page. NOTE: -When a link of a commit reference is found in a thread inside a merge -request, it is automatically converted to a link in the context of the -current merge request. - -### Marking a comment or thread as resolved +When your comment contains a reference to a commit included in the merge request, +it's automatically converted to a link in the context of the current merge request. +For example, `28719b171a056960dfdc0012b625d0b47b123196` becomes +`https://gitlab.example.com/example-group/example-project/-/merge_requests/12345/diffs?commit_id=28719b171a056960dfdc0012b625d0b47b123196`. -You can mark a thread as resolved by selecting the **Resolve thread** -button at the bottom of the thread. +## Add a comment to a commit - +You can add comments and threads to a particular commit. -Alternatively, you can mark each comment as resolved individually. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Repository > Commits**. +1. Below the commits, in the **Comment** field, enter a comment. +1. Select **Comment** or select the down arrow (**{chevron-down}**) to select **Start thread**. - - -### Move all unresolved threads in a merge request to an issue +WARNING: +Threads created this way are lost if the commit ID changes after a +force push. -To continue all open threads from a merge request in a new issue, select -**Resolve all threads in new issue**. +## Add a comment to an image - +In merge requests and commit detail views, you can add a comment to an image. +This comment can also be a thread. -Alternatively, when your project only accepts merge requests [when all threads -are resolved](#only-allow-merge-requests-to-be-merged-if-all-threads-are-resolved), -an **open an issue to resolve them later** link displays in the merge -request widget. +1. Hover your mouse over the image. +1. Select the location where you want to comment. - +An icon is displayed on the image and a comment field is displayed. -This prepares an issue with its content referring to the merge request and -the unresolved threads. + - +## Reply to a comment by sending email -Hitting **Create issue** causes all threads to be marked as resolved and -add a note referring to the newly created issue. +If you have ["reply by email"](../../administration/reply_by_email.md) configured, +you can reply to comments by sending an email. - +- When you reply to a standard comment, another standard comment is created. +- When you reply to a threaded comment, it creates a reply in the thread. -You can now proceed to merge the merge request from the UI. +You can use [Markdown](../markdown.md) and [quick actions](../project/quick_actions.md) in your email replies. -### Moving a single thread to a new issue +## Who can edit comments -To create a new issue for a single thread, you can use the **Resolve this -thread in a new issue** button. +You can edit your own comment at any time. - +Anyone with the [Maintainer role](../permissions.md) or +higher can also edit a comment made by someone else. -This directs you to a new issue prefilled with the content of the -thread, similar to the issues created for delegating multiple -threads at once. Saving the issue marks the thread as resolved and -add a note to the merge request thread referencing the new issue. +## Prevent comments by locking an issue - +You can prevent public comments in an issue or merge request. +When you do, only project members can add and edit comments. -### Only allow merge requests to be merged if all threads are resolved +Prerequisite: -You can prevent merge requests from being merged until all threads are -resolved. +- In merge requests, you must have at least the Developer role. +- In issues, you must have at least the Reporter role. -Navigate to your project's settings page, select the -**Only allow merge requests to be merged if all threads are resolved** check -box and hit **Save** for the changes to take effect. +1. On the right sidebar, next to **Lock issue** or **Lock merge request**, select **Edit**. +1. On the confirmation dialog, select **Lock**. - +Notes are added to the page details. -From now on, you can't merge from the UI until all threads -are resolved. +If an issue or merge request is locked and closed, you cannot reopen it. - +## Mark a comment as confidential -### Automatically resolve merge request diff threads when they become outdated +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207473) in GitLab 13.9. +> - [Deployed behind a feature flag](../feature_flags.md), disabled by default. +> - Disabled on GitLab.com. +> - Not recommended for production use. +> - To use in GitLab self-managed instances, ask a GitLab administrator to enable it. **(FREE SELF)** -You can automatically resolve merge request diff threads on lines modified -with a new push. +WARNING: +This feature might not be available to you. Check the **version history** note above for details. -Navigate to your project's settings page, select the **Automatically resolve -merge request diffs threads on lines changed with a push** check box and hit -**Save** for the changes to take effect. +You can make a comment confidential, so that it is visible only to project members +who have at least the Reporter role. - +1. Below the comment, select the **Make this comment confidential** checkbox. +1. Select **Comment**. -From now on, any threads on a diff are resolved by default if a push -makes that diff section outdated. Threads on lines that don't change and -top-level resolvable threads are not automatically resolved. + -## Commit threads +## Show only comments -You can add comments and threads to a particular commit under your -project's **Repository > Commits**. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/26723) in GitLab 11.5. -WARNING: -Threads created this way are lost if the commit ID changes after a -force push. +For issues and merge requests with many comments, you can filter the page to show comments only. -## Threaded discussions +1. Open a merge request's **Discussion** tab, or epic or issue's **Overview** tab. +1. On the right side of the page, select from the filter: + - **Show all activity**: Display all user comments and system notes + (issue updates, mentions from other issues, changes to the description, and so on). + - **Show comments only**: Display only user comments. + - **Show history only**: Display only activity notes. -While resolvable threads are only available to merge request diffs, -threads can also be added without a diff. You can start a specific -thread which looks like a thread, on issues, commits, snippets, and -merge requests. + -To start a threaded discussion, select the **Comment** button toggle dropdown, -select **Start thread**, and then select **Start thread** when you're ready to -post the comment. +GitLab saves your preference, so it persists when you visit the same page again +from any device you're logged into. - +## Assign an issue to the commenting user -This posts a comment with a single thread to allow you to discuss specific -comments in greater detail. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/191455) in GitLab 13.1. - +You can assign an issue to a user who made a comment. -## Image threads +1. In the comment, select the **More Actions** menu. +1. Select **Assign to commenting user**. -Sometimes a thread is revolved around an image. With image threads, -you can easily target a specific coordinate of an image and start a thread -around it. Image threads are available in merge requests and commit detail views. + -To start an image thread, hover your mouse over the image. Your mouse pointer -should convert into an icon, indicating that the image is available for commenting. -Simply click anywhere on the image to create a new thread. +Select the button again to unassign the commenter. - +## Create a thread by replying to a standard comment -After you select the image, a comment form is displayed that would be the start -of your thread. After you save your comment, a new badge is displayed on -top of your image. This badge represents your thread. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/30299) in GitLab 11.9. -NOTE: -This thread badge is typically associated with a number that is only used as a visual -reference for each thread. In the merge request thread tab, -this badge is indicated with a comment icon, because each thread renders a new -image section. +When you reply to a standard comment, you create a thread. -Image threads also work on diffs that replace an existing image. In this diff view -mode, you can toggle the different view modes and still see the thread point badges. +Prerequisites: -| 2-up | Swipe | Onion Skin | -|:-----------:|:----------:|:----------:| -|  |  |  | +- You must have at least the [Guest role](../permissions.md#project-members-permissions). +- You must be in an issue, merge request, or epic. Commits and snippets threads are not supported. -Image threads also work well with resolvable threads. Resolved threads -on diffs (not on the merge request discussion tab) appear collapsed on page -load and have a corresponding badge counter to match the counter on the image. +To create a thread by replying to a comment: - +1. On the top right of the comment, select **{comment}** (**Reply to comment**). -## Lock discussions +  -For large projects with many contributors, it may be useful to stop threads -in issues or merge requests in these scenarios: + The reply area is displayed. -- The project maintainer has already resolved the thread and it is not helpful - for continued feedback. -- The project maintainer has already directed new conversation - to newer issues or merge requests. -- The people participating in the thread are trolling, abusive, or otherwise - being unproductive. +1. Type your reply. +1. Select **Comment** or **Add comment now** (depending on where in the UI you are replying). -In these cases, a user with Developer permissions or higher in the project can lock (and unlock) -an issue or a merge request, using the "Lock" section in the sidebar. For issues, -a user with Reporter permissions can lock (and unlock). +The top comment is converted to a thread. -| Unlock | Lock | -| :-----------: | :----------: | -|  |  | +## Create a thread without replying to a comment -System notes indicate locking and unlocking. +You can create a thread without replying to a standard comment. - +Prerequisites: -In a locked issue or merge request, only team members can add new comments and -edit existing comments. Non-team members are restricted from adding or editing comments. +- You must have at least the [Guest role](../permissions.md#project-members-permissions). +- You must be in an issue, merge request, commit, or snippet. -| Team member | Non-team member | -| :-----------: | :----------: | -|  |  | +To create a thread: -Additionally, locked issues and merge requests can't be reopened. +1. Type a comment. +1. Below the comment, to the right of the **Comment** button, select the down arrow (**{chevron-down}**). +1. From the list, select **Start thread**. +1. Select **Start thread** again. -## Confidential Comments +A threaded comment is created. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207473) in GitLab 13.9. -> - [Deployed behind a feature flag](../feature_flags.md), disabled by default. -> - Disabled on GitLab.com. -> - Not recommended for production use. -> - To use in GitLab self-managed instances, ask a GitLab administrator to enable it. **(FREE SELF)** + -WARNING: -This feature might not be available to you. Check the **version history** note above for details. +## Resolve a thread -When creating a comment, you can make it visible only to the project members (users with Reporter and higher permissions). +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5022) in GitLab 8.11. +> - Resolvable threads can be added only to merge request diffs. +> - Resolving comments individually was [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/28750) in GitLab 13.6. -To create a confidential comment, select the **Make this comment confidential** check box before you submit it. +You can resolve a thread when you want to finish a conversation. - +Prerequisites: -## Filtering notes +- You must have at least the [Developer role](../permissions.md#project-members-permissions) + or be the author of the change being reviewed. +- You must be in an issue, merge request, commit, or snippet. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/26723) in GitLab 11.5. +To resolve a thread: -For issues with many comments like activity notes and user comments, sometimes -finding useful information can be hard. There is a way to filter comments from single notes and threads for merge requests and issues. +1. Go to the thread. +1. Do one of the following: + - In the top right of the original comment, select the **Resolve thread** (**{check-circle}**) icon. + - Below the last reply, in the **Reply** field, select **Resolve thread**. + - Below the last reply, in the **Reply** field, enter text, select the **Resolve thread** checkbox, and select **Add comment now**. -From a merge request's **Discussion** tab, or from an epic/issue overview, find the filter's dropdown menu on the right side of the page, from which you can choose one of the following options: +At the top of the page, the number of unresolved threads is updated. -- **Show all activity**: displays all user comments and system notes - (issue updates, mentions from other issues, changes to the description, etc). -- **Show comments only**: only displays user comments in the list. -- **Show history only**: only displays activity notes. + - +### Move all unresolved threads in a merge request to an issue -After you select one of the filters in a given issue or merge request, GitLab saves -your preference, so that it persists when you visit the same page again -from any device you're logged into. +If you have multiple unresolved threads in a merge request, you can +create an issue to resolve them separately. -## Start a thread by replying to a standard comment +- In the merge request, at the top of the page, select **Resolve all threads in new issue**. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/30299) in GitLab 11.9 +  -To reply to a standard (non-thread) comment, you can use the **Reply to comment** button. +All threads are marked as resolved and a link is added from the merge request to +the newly created issue. - +### Move one unresolved thread in a merge request to an issue -The **Reply to comment** button is only displayed if you have permissions to reply to an existing thread, or start a thread from a standard comment. +If you have one specific unresolved thread in a merge request, you can +create an issue to resolve it separately. -Selecting the **Reply to comment** button brings the reply area into focus and you can type your reply. +- In the merge request, under the last reply to the thread, next to the + **Resolve thread** button, select **Resolve this thread in a new issue**. - +  -Replying to a non-thread comment converts the non-thread comment to a -thread after the reply is submitted. This conversion is considered an edit -to the original comment, so a note about when it was last edited appears underneath it. +The thread is marked as resolved and a link is added from the merge request to +the newly created issue. -This feature exists only for issues, merge requests, and epics. Commits, snippets, and merge request diff threads are -not supported yet. +### Prevent merge unless all threads are resolved -## Assign an issue to the commenting user +You can prevent merge requests from being merged until all threads are +resolved. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/191455) in GitLab 13.1. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > General**. +1. Expand **Merge requests**. +1. Under **Merge checks**, select the **All discussions must be resolved** checkbox. +1. Select **Save changes**. -You can assign an issue to a user who made a comment. +### Automatically resolve threads in a merge request when they become outdated -In the comment, select the **More Actions** menu, and then select **Assign to commenting user**. +You can set merge requests to automatically resolve threads when lines are modified +with a new push. -Select the button again to unassign the commenter. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > General**. +1. Expand **Merge requests**. +1. Under **Merge options**, select the + **Automatically resolve merge request diff discussions when they become outdated** checkbox. +1. Select **Save changes**. - +Threads are now resolved if a push makes a diff section outdated. +Threads on lines that don't change and top-level resolvable threads are not resolved. -## Enable or disable Confidential Comments **(FREE SELF)** +## Enable or disable confidential comments **(FREE SELF)** -Confidential Comments is under development and not ready for production use. It is +Confidential comments are under development and not ready for production use. The feature is deployed behind a feature flag that is **disabled by default**. [GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) can enable it. |