debian-mirror-gitlab/doc/user/discussions/index.md

308 lines
11 KiB
Markdown
Raw Normal View History

2020-06-23 00:09:42 +05:30
---
2020-10-24 23:57:45 +05:30
stage: Create
2021-04-17 20:07:23 +05:30
group: Code Review
2021-02-22 17:27:13 +05:30
info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments"
2020-10-24 23:57:45 +05:30
type: reference, howto
2020-06-23 00:09:42 +05:30
---
2021-09-30 23:02:18 +05:30
# Comments and threads **(FREE)**
2017-08-17 22:00:37 +05:30
2021-09-04 01:27:46 +05:30
GitLab encourages communication through comments, threads, and
[code suggestions](../project/merge_requests/reviews/suggestions.md).
2017-08-17 22:00:37 +05:30
2021-09-30 23:02:18 +05:30
There are two types of comments:
2017-08-17 22:00:37 +05:30
2021-09-30 23:02:18 +05:30
- A standard comment.
2021-11-11 11:23:49 +05:30
- A comment in a thread, which can be [resolved](#resolve-a-thread).
2017-08-17 22:00:37 +05:30
2021-09-30 23:02:18 +05:30
In a comment, you can enter [Markdown](../markdown.md) and use [quick actions](../project/quick_actions.md).
2018-05-09 12:01:36 +05:30
2021-09-30 23:02:18 +05:30
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.
2017-08-17 22:00:37 +05:30
2021-09-30 23:02:18 +05:30
## Places you can add comments
2019-12-21 20:55:43 +05:30
2021-09-30 23:02:18 +05:30
You can create comments in places like:
2017-08-17 22:00:37 +05:30
2021-09-30 23:02:18 +05:30
- Commit diffs
- Commits
- Designs
- Epics
- Issues
- Merge requests
- Snippets
2018-03-17 18:26:18 +05:30
2021-09-30 23:02:18 +05:30
Each object can have as many as 5,000 comments.
2018-03-17 18:26:18 +05:30
2021-09-30 23:02:18 +05:30
## Add a comment to a merge request diff
2018-03-17 18:26:18 +05:30
2021-09-30 23:02:18 +05:30
You can add comments to a merge request diff. These comments
persist, even when you:
2018-03-17 18:26:18 +05:30
2021-09-30 23:02:18 +05:30
- Force-push after a rebase.
- Amend a commit.
2018-03-17 18:26:18 +05:30
2021-09-30 23:02:18 +05:30
To add a commit diff comment:
2018-03-17 18:26:18 +05:30
2021-09-30 23:02:18 +05:30
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.
2021-11-11 11:23:49 +05:30
1. By the line you want to comment on, hover over the line number and select **Comment** (**{comment}**).
You can select multiple lines by dragging the **Comment** (**{comment}**) icon.
1. Enter your comment and select **Start a review** or **Add comment now**.
2018-03-17 18:26:18 +05:30
2021-09-30 23:02:18 +05:30
The comment is displayed on the merge request's **Discussions** tab.
2018-03-17 18:26:18 +05:30
2021-09-30 23:02:18 +05:30
The comment is not displayed on your project's **Repository > Commits** page.
2018-03-17 18:26:18 +05:30
2021-02-22 17:27:13 +05:30
NOTE:
2021-09-30 23:02:18 +05:30
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`.
2017-08-17 22:00:37 +05:30
2021-09-30 23:02:18 +05:30
## Add a comment to a commit
2017-08-17 22:00:37 +05:30
2021-09-30 23:02:18 +05:30
You can add comments and threads to a particular commit.
2017-08-17 22:00:37 +05:30
2021-09-30 23:02:18 +05:30
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**.
2017-08-17 22:00:37 +05:30
2021-09-30 23:02:18 +05:30
WARNING:
Threads created this way are lost if the commit ID changes after a
force push.
2017-08-17 22:00:37 +05:30
2021-09-30 23:02:18 +05:30
## Add a comment to an image
2017-08-17 22:00:37 +05:30
2021-09-30 23:02:18 +05:30
In merge requests and commit detail views, you can add a comment to an image.
This comment can also be a thread.
2017-08-17 22:00:37 +05:30
2021-09-30 23:02:18 +05:30
1. Hover your mouse over the image.
1. Select the location where you want to comment.
2017-08-17 22:00:37 +05:30
2021-09-30 23:02:18 +05:30
An icon is displayed on the image and a comment field is displayed.
2017-08-17 22:00:37 +05:30
2021-09-30 23:02:18 +05:30
![Start image thread](img/start_image_discussion.gif)
2017-08-17 22:00:37 +05:30
2021-09-30 23:02:18 +05:30
## Reply to a comment by sending email
2017-08-17 22:00:37 +05:30
2021-09-30 23:02:18 +05:30
If you have ["reply by email"](../../administration/reply_by_email.md) configured,
you can reply to comments by sending an email.
2017-08-17 22:00:37 +05:30
2021-09-30 23:02:18 +05:30
- 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.
2017-08-17 22:00:37 +05:30
2021-09-30 23:02:18 +05:30
You can use [Markdown](../markdown.md) and [quick actions](../project/quick_actions.md) in your email replies.
2017-08-17 22:00:37 +05:30
2021-09-30 23:02:18 +05:30
## Who can edit comments
2017-08-17 22:00:37 +05:30
2021-09-30 23:02:18 +05:30
You can edit your own comment at any time.
2017-08-17 22:00:37 +05:30
2021-09-30 23:02:18 +05:30
Anyone with the [Maintainer role](../permissions.md) or
higher can also edit a comment made by someone else.
2017-08-17 22:00:37 +05:30
2021-09-30 23:02:18 +05:30
## Prevent comments by locking an issue
2017-08-17 22:00:37 +05:30
2021-09-30 23:02:18 +05:30
You can prevent public comments in an issue or merge request.
When you do, only project members can add and edit comments.
2017-08-17 22:00:37 +05:30
2021-09-30 23:02:18 +05:30
Prerequisite:
2017-08-17 22:00:37 +05:30
2021-09-30 23:02:18 +05:30
- In merge requests, you must have at least the Developer role.
- In issues, you must have at least the Reporter role.
2017-08-17 22:00:37 +05:30
2021-09-30 23:02:18 +05:30
1. On the right sidebar, next to **Lock issue** or **Lock merge request**, select **Edit**.
1. On the confirmation dialog, select **Lock**.
2017-08-17 22:00:37 +05:30
2021-09-30 23:02:18 +05:30
Notes are added to the page details.
2017-08-17 22:00:37 +05:30
2021-09-30 23:02:18 +05:30
If an issue or merge request is locked and closed, you cannot reopen it.
2017-08-17 22:00:37 +05:30
2021-09-30 23:02:18 +05:30
## Mark a comment as confidential
2017-08-17 22:00:37 +05:30
2021-09-30 23:02:18 +05:30
> - [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)**
2018-03-17 18:26:18 +05:30
2021-09-30 23:02:18 +05:30
WARNING:
This feature might not be available to you. Check the **version history** note above for details.
2018-03-17 18:26:18 +05:30
2021-09-30 23:02:18 +05:30
You can make a comment confidential, so that it is visible only to project members
who have at least the Reporter role.
2018-03-17 18:26:18 +05:30
2021-09-30 23:02:18 +05:30
1. Below the comment, select the **Make this comment confidential** checkbox.
1. Select **Comment**.
2018-03-17 18:26:18 +05:30
2021-09-30 23:02:18 +05:30
![Confidential comments](img/confidential_comments_v13_9.png)
2018-03-17 18:26:18 +05:30
2021-10-27 15:23:28 +05:30
You can also make an [entire issue confidential](../project/issues/confidential_issues.md).
2021-09-30 23:02:18 +05:30
## Show only comments
2018-03-17 18:26:18 +05:30
2021-09-30 23:02:18 +05:30
> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/26723) in GitLab 11.5.
2018-03-17 18:26:18 +05:30
2021-09-30 23:02:18 +05:30
For issues and merge requests with many comments, you can filter the page to show comments only.
2018-03-17 18:26:18 +05:30
2021-09-30 23:02:18 +05:30
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.
2017-08-17 22:00:37 +05:30
2021-09-30 23:02:18 +05:30
![Notes filters dropdown options](img/index_notes_filters.png)
2017-08-17 22:00:37 +05:30
2021-09-30 23:02:18 +05:30
GitLab saves your preference, so it persists when you visit the same page again
from any device you're logged into.
2017-08-17 22:00:37 +05:30
2021-09-30 23:02:18 +05:30
## Assign an issue to the commenting user
2017-08-17 22:00:37 +05:30
2021-09-30 23:02:18 +05:30
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/191455) in GitLab 13.1.
2017-08-17 22:00:37 +05:30
2021-09-30 23:02:18 +05:30
You can assign an issue to a user who made a comment.
2017-08-17 22:00:37 +05:30
2021-11-11 11:23:49 +05:30
1. In the comment, select the **More Actions** (**{ellipsis_v}**) menu.
1. Select **Assign to commenting user**:
![Assign to commenting user](img/quickly_assign_commenter_v13_1.png)
1. To unassign the commenter, select the button again.
2018-03-17 18:26:18 +05:30
2021-09-30 23:02:18 +05:30
## Create a thread by replying to a standard comment
2018-03-17 18:26:18 +05:30
2021-09-30 23:02:18 +05:30
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/30299) in GitLab 11.9.
2018-03-17 18:26:18 +05:30
2021-09-30 23:02:18 +05:30
When you reply to a standard comment, you create a thread.
2018-03-17 18:26:18 +05:30
2021-09-30 23:02:18 +05:30
Prerequisites:
2018-03-17 18:26:18 +05:30
2021-09-30 23:02:18 +05:30
- 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.
2018-03-17 18:26:18 +05:30
2021-09-30 23:02:18 +05:30
To create a thread by replying to a comment:
2018-03-17 18:26:18 +05:30
2021-11-11 11:23:49 +05:30
1. On the top right of the comment, select **Reply to comment** (**{comment}**).
2018-03-17 18:26:18 +05:30
2021-09-30 23:02:18 +05:30
![Reply to comment button](img/reply_to_comment_button.png)
2018-03-17 18:26:18 +05:30
2021-09-30 23:02:18 +05:30
The reply area is displayed.
2018-03-17 18:26:18 +05:30
2021-11-11 11:23:49 +05:30
1. Enter your reply.
2021-09-30 23:02:18 +05:30
1. Select **Comment** or **Add comment now** (depending on where in the UI you are replying).
2018-03-17 18:26:18 +05:30
2021-09-30 23:02:18 +05:30
The top comment is converted to a thread.
2018-03-17 18:26:18 +05:30
2021-09-30 23:02:18 +05:30
## Create a thread without replying to a comment
2018-03-17 18:26:18 +05:30
2021-09-30 23:02:18 +05:30
You can create a thread without replying to a standard comment.
2018-03-17 18:26:18 +05:30
2021-09-30 23:02:18 +05:30
Prerequisites:
2018-03-17 18:26:18 +05:30
2021-09-30 23:02:18 +05:30
- You must have at least the [Guest role](../permissions.md#project-members-permissions).
- You must be in an issue, merge request, commit, or snippet.
2018-03-17 18:26:18 +05:30
2021-09-30 23:02:18 +05:30
To create a thread:
2018-03-17 18:26:18 +05:30
2021-11-11 11:23:49 +05:30
1. Enter a comment.
2021-09-30 23:02:18 +05:30
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.
2018-11-20 20:47:30 +05:30
2021-09-30 23:02:18 +05:30
A threaded comment is created.
2021-03-11 19:13:27 +05:30
2021-09-30 23:02:18 +05:30
![Thread comment](img/discussion_comment.png)
2021-03-11 19:13:27 +05:30
2021-09-30 23:02:18 +05:30
## Resolve a thread
2021-03-11 19:13:27 +05:30
2021-09-30 23:02:18 +05:30
> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5022) in GitLab 8.11.
> - Resolving comments individually was [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/28750) in GitLab 13.6.
2021-03-11 19:13:27 +05:30
2021-11-11 11:23:49 +05:30
In a merge request, you can resolve a thread when you want to finish a conversation.
2021-03-11 19:13:27 +05:30
2021-09-30 23:02:18 +05:30
Prerequisites:
2021-03-11 19:13:27 +05:30
2021-09-30 23:02:18 +05:30
- You must have at least the [Developer role](../permissions.md#project-members-permissions)
or be the author of the change being reviewed.
2021-11-11 11:23:49 +05:30
- Resolvable threads can be added only to merge requests. It doesn't work
for comments in issues, commits, or snippets.
2018-12-13 13:39:08 +05:30
2021-09-30 23:02:18 +05:30
To resolve a thread:
2018-12-13 13:39:08 +05:30
2021-09-30 23:02:18 +05:30
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**.
2018-12-13 13:39:08 +05:30
2021-11-11 11:23:49 +05:30
At the top of the page, the number of unresolved threads is updated:
2018-12-13 13:39:08 +05:30
2021-09-30 23:02:18 +05:30
![Count of unresolved threads](img/unresolved_threads_v14_1.png)
2018-12-13 13:39:08 +05:30
2021-09-30 23:02:18 +05:30
### Move all unresolved threads in a merge request to an issue
2018-12-13 13:39:08 +05:30
2021-09-30 23:02:18 +05:30
If you have multiple unresolved threads in a merge request, you can
2021-11-11 11:23:49 +05:30
create an issue to resolve them separately. In the merge request, at the top of the page,
select **Create issue to resolve all threads** (**{issue-new}**):
2018-12-13 13:39:08 +05:30
2021-11-11 11:23:49 +05:30
![Open new issue for all unresolved threads](img/create-new-issue_v14_3.png)
2019-07-07 11:18:12 +05:30
2021-11-11 11:23:49 +05:30
All threads are marked as resolved, and a link is added from the merge request to
2021-09-30 23:02:18 +05:30
the newly created issue.
2019-07-07 11:18:12 +05:30
2021-09-30 23:02:18 +05:30
### Move one unresolved thread in a merge request to an issue
2019-07-07 11:18:12 +05:30
2021-09-30 23:02:18 +05:30
If you have one specific unresolved thread in a merge request, you can
2021-11-11 11:23:49 +05:30
create an issue to resolve it separately. In the merge request, under the last reply
to the thread, next to **Resolve thread**, select **Create issue to resolve thread** (**{issue-new}**):
2019-07-07 11:18:12 +05:30
2021-11-11 11:23:49 +05:30
![Create issue for thread](img/new-issue-one-thread_v14_3.png)
2019-07-07 11:18:12 +05:30
2021-11-11 11:23:49 +05:30
The thread is marked as resolved, and a link is added from the merge request to
2021-09-30 23:02:18 +05:30
the newly created issue.
2019-07-07 11:18:12 +05:30
2021-09-30 23:02:18 +05:30
### Prevent merge unless all threads are resolved
2020-06-23 00:09:42 +05:30
2021-09-30 23:02:18 +05:30
You can prevent merge requests from being merged until all threads are
resolved.
2020-06-23 00:09:42 +05:30
2021-09-30 23:02:18 +05:30
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**.
2020-06-23 00:09:42 +05:30
2021-09-30 23:02:18 +05:30
### Automatically resolve threads in a merge request when they become outdated
2020-06-23 00:09:42 +05:30
2021-09-30 23:02:18 +05:30
You can set merge requests to automatically resolve threads when lines are modified
with a new push.
2020-06-23 00:09:42 +05:30
2021-09-30 23:02:18 +05:30
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**.
2020-06-23 00:09:42 +05:30
2021-09-30 23:02:18 +05:30
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.
2021-03-11 19:13:27 +05:30
2021-09-30 23:02:18 +05:30
## Enable or disable confidential comments **(FREE SELF)**
2021-03-11 19:13:27 +05:30
2021-09-30 23:02:18 +05:30
Confidential comments are under development and not ready for production use. The feature is
2021-03-11 19:13:27 +05:30
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.
To enable it:
```ruby
Feature.enable(:confidential_notes)
```
To disable it:
```ruby
Feature.disable(:confidential_notes)
```