index.md 21 KB
Newer Older
1
# Threads
2

3 4
The ability to contribute conversationally is offered throughout GitLab.

5
You can leave a comment in the following places:
6

7 8 9 10 11 12
- Issues
- Epics **(ULTIMATE)**
- Merge requests
- Snippets
- Commits
- Commit diffs
13

14
There are standard comments, and you also have the option to create a comment
15
in the form of a thread. A comment can also be [turned into a thread](#start-a-thread-by-replying-to-a-standard-comment)
16 17 18 19
when it receives a reply.

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
20
higher can also edit a comment made by someone else.
21

22
You can also reply to a comment notification email to reply to the comment if
Evan Read's avatar
Evan Read committed
23
[Reply by email] is configured for your GitLab instance. Replying to a standard comment
24
creates another standard comment. Replying to a threaded comment creates a reply in the thread. Email replies support
25
[Markdown] and [quick actions], just as if you replied from the web.
26

27
NOTE: **Note:**
28
There is a limit of 5,000 comments for every object, for example: issue, epic, and merge request.
29

30
## Resolvable comments and threads
31

32
> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/5022) in GitLab 8.11.
33
> - Resolvable threads can be added only to merge request diffs.
34

35
Thread resolution helps keep track of progress during planning or code review.
36

37
Every standard comment or thread in merge requests, commits, commit diffs, and
38 39
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.
40 41 42
If the thread has been resolved and a non-member unresolves their own response,
this will also unresolve the discussion thread.
If the non-member then resolves this same response, this will resolve the discussion thread.
43

44 45
The need to resolve all standard comments or threads prevents you from forgetting
to address feedback and lets you hide threads that are no longer relevant.
46

47
!["A thread between two people on a piece of code"](img/thread_view.png)
48

49
### Commit threads in the context of a merge request
50 51 52

> [Introduced][ce-31847] in GitLab 10.3.

53 54
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 will
55 56 57 58 59
persist through a commit ID change when:

- force-pushing after a rebase
- amending a commit

60
To create a commit diff thread:
61 62 63 64

1. Navigate to the merge request **Commits** tab. A list of commits that
   constitute the merge request will be shown.

65
   ![Merge request commits tab](img/merge_request_commits_tab.png)
66 67 68 69

1. Navigate to a specific commit, click on the **Changes** tab (where you
   will only be presented diffs from the selected commit), and leave a comment.

70
   ![Commit diff discussion in merge request context](img/commit_comment_mr_context.png)
71

72
1. Any threads created this way will be shown in the merge request's
73 74
   **Discussions** tab and are resolvable.

75
   ![Merge request Discussions tab](img/commit_comment_mr_discussions_tab.png)
76

77
Threads created this way will only appear in the original merge request
78 79 80 81
and not when navigating to that commit under your project's
**Repository > Commits** page.

TIP: **Tip:**
82
When a link of a commit reference is found in a thread inside a merge
83 84 85
request, it will be automatically converted to a link in the context of the
current merge request.

86
### Jumping between unresolved threads
87 88

When a merge request has a large number of comments it can be difficult to track
89 90
what remains unresolved. You can jump between unresolved threads with the
Jump button next to the Reply field on a thread.
91

92 93
You can also jump to the first unresolved thread from the button next to the
resolved threads tracker.
94

95 96 97 98 99
You can also use keyboard shortcuts to navigate among threads:

- Use <kbd>n</kbd> to jump to the next unresolved thread.
- Use <kbd>p</kbd> to jump to the previous unresolved thread.

100
!["8/9 threads resolved"](img/threads_resolved.png)
101

102
### Marking a comment or thread as resolved
103

104 105
You can mark a thread as resolved by clicking the **Resolve thread**
button at the bottom of the thread.
106

107
!["Resolve thread" button](img/resolve_thread_button.png)
108 109 110

Alternatively, you can mark each comment as resolved individually.

111
!["Resolve comment" button](img/resolve_comment_button.png)
112

113
### Move all unresolved threads in a merge request to an issue
114 115 116

> [Introduced][ce-8266] in GitLab 9.1

117 118
To continue all open threads from a merge request in a new issue, click the
**Resolve all threads in new issue** button.
119

120
![Open new issue for all unresolved threads](img/btn_new_issue_for_all_threads.png)
121

122 123
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),
124 125
there will be an **open an issue to resolve them later** link in the merge
request widget.
126

127
![Link in merge request widget](img/resolve_thread_open_issue.png)
128

129
This will prepare an issue with its content referring to the merge request and
130
the unresolved threads.
131

132
![Issue mentioning threads in a merge request](img/preview_issue_for_threads.png)
133

134
Hitting **Submit issue** will cause all threads to be marked as resolved and
135
add a note referring to the newly created issue.
136

137
![Mark threads as resolved notice](img/resolve_thread_issue_notice.png)
138

139
You can now proceed to merge the merge request from the UI.
140

141
### Moving a single thread to a new issue
142

143
> [Introduced][ce-8266] in GitLab 9.1
144

145 146
To create a new issue for a single thread, you can use the **Resolve this
thread in a new issue** button.
147

148
![Create issue for thread](img/new_issue_for_thread.png)
149

150
This will direct you to a new issue prefilled with the content of the
151 152 153
thread, similar to the issues created for delegating multiple
threads at once. Saving the issue will mark the thread as resolved and
add a note to the merge request thread referencing the new issue.
154

155
![New issue for a single thread](img/preview_issue_for_thread.png)
156

157
### Only allow merge requests to be merged if all threads are resolved
158 159 160

> [Introduced][ce-7125] in GitLab 8.14.

161
You can prevent merge requests from being merged until all threads are
162
resolved.
163 164

Navigate to your project's settings page, select the
165
**Only allow merge requests to be merged if all threads are resolved** check
166 167
box and hit **Save** for the changes to take effect.

168
![Only allow merge if all the threads are resolved settings](img/only_allow_merge_if_all_threads_are_resolved.png)
169

170
From now on, you will not be able to merge from the UI until all threads
171 172
are resolved.

173
![Only allow merge if all the threads are resolved message](img/resolve_thread_open_issue.png)
174

175
### Automatically resolve merge request diff threads when they become outdated
176

177
> [Introduced][ce-14053] in GitLab 10.0.
178

179
You can automatically resolve merge request diff threads on lines modified
180 181 182
with a new push.

Navigate to your project's settings page, select the **Automatically resolve
183
merge request diffs threads on lines changed with a push** check box and hit
184 185
**Save** for the changes to take effect.

186
![Automatically resolve merge request diff threads when they become outdated](img/automatically_resolve_outdated_discussions.png)
187

188 189 190
From now on, any threads on a diff will be 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.
191

192
## Commit threads
193

194
You can add comments and threads to a particular commit under your
195 196 197
project's **Repository > Commits**.

CAUTION: **Attention:**
198
Threads created this way will be lost if the commit ID changes after a
199 200
force push.

201
## Threaded discussions
202

203
> [Introduced][ce-7527] in GitLab 9.1.
204

205 206 207
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 will look like a thread, on issues, commits, snippets, and
208
merge requests.
209

210
To start a threaded discussion, click on the **Comment** button toggle dropdown,
211
select **Start thread** and click **Start thread** when you're ready to
212
post the comment.
213 214 215

![Comment type toggle](img/comment_type_toggle.gif)

216 217
This will post a comment with a single thread to allow you to discuss specific
comments in greater detail.
218

219
![Thread comment](img/discussion_comment.png)
220

221
## Image threads
Clement Ho's avatar
Clement Ho committed
222

223
> [Introduced][ce-14061] in GitLab 10.1.
Clement Ho's avatar
Clement Ho committed
224

225 226 227
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.
Clement Ho's avatar
Clement Ho committed
228

229
To start an image thread, hover your mouse over the image. Your mouse pointer
Clement Ho's avatar
Clement Ho committed
230
should convert into an icon, indicating that the image is available for commenting.
231
Simply click anywhere on the image to create a new thread.
Clement Ho's avatar
Clement Ho committed
232

233
![Start image thread](img/start_image_discussion.gif)
Clement Ho's avatar
Clement Ho committed
234 235

After you click on the image, a comment form will be displayed that would be the start
236 237
of your thread. Once you save your comment, you will see a new badge displayed on
top of your image. This badge represents your thread.
Clement Ho's avatar
Clement Ho committed
238 239

>**Note:**
240 241 242
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 will be indicated with a comment icon since each thread will render a new
Clement Ho's avatar
Clement Ho committed
243 244
image section.

245 246
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.
Clement Ho's avatar
Clement Ho committed
247 248 249 250 251

| 2-up | Swipe | Onion Skin |
| :-----------: | :----------: | :----------: |
| ![2-up view](img/two_up_view.png) | ![swipe view](img/swipe_view.png) | ![onion skin view](img/onion_skin_view.png) |

252
Image threads also work well with resolvable threads. Resolved threads
Clement Ho's avatar
Clement Ho committed
253 254 255
on diffs (not on the merge request discussion tab) will appear collapsed on page
load and will have a corresponding badge counter to match the counter on the image.

256
![Image resolved thread](img/image_resolved_discussion.png)
Clement Ho's avatar
Clement Ho committed
257

Victor Wu's avatar
Victor Wu committed
258
## Lock discussions
259 260 261

> [Introduced][ce-14531] in GitLab 10.1.

262
For large projects with many contributors, it may be useful to stop threads
Victor Wu's avatar
Victor Wu committed
263
in issues or merge requests in these scenarios:
264

265 266 267
- The project maintainer has already resolved the thread and it is not helpful
  for continued feedback.
- The project maintainer has already directed new conversation
268
  to newer issues or merge requests.
269
- The people participating in the thread are trolling, abusive, or otherwise
270
  being unproductive.
271

272 273 274
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).
275

Victor Wu's avatar
Victor Wu committed
276
| Unlock | Lock |
277 278 279
| :-----------: | :----------: |
| ![Turn off discussion lock](img/turn_off_lock.png) | ![Turn on discussion lock](img/turn_on_lock.png) |

Victor Wu's avatar
Victor Wu committed
280
System notes indicate locking and unlocking.
281 282 283

![Discussion lock system notes](img/discussion_lock_system_notes.png)

Clement Ho's avatar
Clement Ho committed
284
In a locked issue or merge request, only team members can add new comments and
Victor Wu's avatar
Victor Wu committed
285
edit existing comments. Non-team members are restricted from adding or editing comments.
286

Victor Wu's avatar
Victor Wu committed
287
| Team member | Non-team member |
288 289 290
| :-----------: | :----------: |
| ![Comment form member](img/lock_form_member.png) | ![Comment form non-member](img/lock_form_non_member.png) |

291
Additionally, locked issues and merge requests can not be reopened.
292

293
## Merge Request Reviews **(PREMIUM)**
294

295
> [Introduced](https://gitlab.com/gitlab-org/gitlab/merge_requests/4213) in GitLab 11.4.
296 297 298 299 300 301 302 303 304 305 306 307 308 309 310

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.

![Starting a review](img/mr_review_start.png)

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:

311
- **Finish review**: Submits all comments that are part of the review, making them visible to other users.
312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327
- **Add comment now**: Submits the specific comment as a regular comment instead of as part of the review.

![A comment that is part of a review](img/pending_review_comment.png)

You can use [quick actions] inside review comments. The comment will show the actions that will be performed once published.

![A review comment with quick actions](img/review_comment_quickactions.png)

To add more comments to a review, start writing a comment as normal and click the **Add to review** button.

![Adding a second comment to a review](img/mr_review_second_comment.png)

This will add the comment to the review.

![Second review comment](img/mr_review_second_comment_added.png)

328
### Resolving/Unresolving threads
329

330
Review comments can also resolve/unresolve [resolvable threads](#resolvable-comments-and-threads).
331
When replying to a comment, you will see a checkbox that you can click in order to resolve or unresolve
332
the thread once published.
333 334 335

![Resolve checkbox](img/mr_review_resolve.png)

336
If a particular pending comment will resolve or unresolve the thread, this will be shown on the pending
337 338 339
comment itself.

![Resolve status](img/mr_review_resolve2.png)
340 341

![Unresolve status](img/mr_review_unresolve.png)
342 343 344 345 346 347 348 349

### 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.
350 351
  Clicking **Submit review** will publish all comments. Any quick actions
  submitted are performed at this time.
352

353 354 355 356
Alternatively, to finish the entire review from a pending comment:

- Click the **Finish review** button on the comment.
- Use the `/submit_review` [quick action](../project/quick_actions.md) in the text of non-review comment.
357 358 359 360 361 362 363 364

![Review submission](img/review_preview.png)

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.

365 366
## Filtering notes

367
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/26723) in GitLab 11.5.
368

369
For issues with many comments like activity notes and user comments, sometimes
370
finding useful information can be hard. There is a way to filter comments from single notes and threads for merge requests and issues.
371

372
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:
373 374

- **Show all activity**: displays all user comments and system notes
375
  (issue updates, mentions from other issues, changes to the description, etc).
376
- **Show comments only**: only displays user comments in the list.
377
- **Show history only**: only displays activity notes.
378 379 380 381 382 383 384

![Notes filters dropdown options](img/index_notes_filters.png)

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.

385 386
## Suggest Changes

387
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/18008) in GitLab 11.6.
388

389
As a reviewer, you're able to suggest code changes with a simple
390
Markdown syntax in Merge Request Diff threads. Then, the
391
Merge Request author (or other users with appropriate
392
[permission](../permissions.md)) is able to apply these
393 394
Suggestions with a click, which will generate a commit in
the merge request authored by the user that applied them.
395 396

1. Choose a line of code to be changed, add a new comment, then click
397
   on the **Insert suggestion** icon in the toolbar:
398

399
   ![Add a new comment](img/suggestion_button_v12_7.png)
400

401 402
1. In the comment, add your suggestion to the pre-populated code block:

403
   ![Add a suggestion into a code block tagged properly](img/make_suggestion_v12_7.png)
404 405 406

1. Click **Comment**.

407 408 409
   NOTE: **Note:**
   If you're using GitLab Premium, GitLab.com Silver, and higher tiers, the thread will display [Review](#merge-request-reviews-premium) options. Click either **Start a review**, **Add comment now**, or **Add to review** to obtain the same result.

410
   The Suggestion in the comment can be applied by the merge request author
411
   directly from the merge request:
412

413
   ![Apply suggestions](img/apply_suggestion_v12_7.png)
414

415
Once the author applies a Suggestion, it will be marked with the **Applied** label,
416
the thread will be automatically resolved, and GitLab will create a new commit
417 418
and push the suggested change directly into the codebase in the merge request's
branch. [Developer permission](../permissions.md) is required to do so.
419

420
### Multi-line Suggestions
Oswaldo Ferreira's avatar
Oswaldo Ferreira committed
421

422
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/53310) in GitLab 11.10.
Oswaldo Ferreira's avatar
Oswaldo Ferreira committed
423

424 425
Reviewers can also suggest changes to multiple lines with a single Suggestion
within merge request diff threads by adjusting the range offsets. The
426
offsets are relative to the position of the diff thread, and specify the
427
range to be replaced by the suggestion when it is applied.
Oswaldo Ferreira's avatar
Oswaldo Ferreira committed
428 429 430

![Multi-line suggestion syntax](img/multi-line-suggestion-syntax.png)

431
In the example above, the Suggestion covers three lines above and four lines
432 433
below the commented line. When applied, it would replace from 3 lines _above_
to 4 lines _below_ the commented line, with the suggested change.
Oswaldo Ferreira's avatar
Oswaldo Ferreira committed
434 435 436 437

![Multi-line suggestion preview](img/multi-line-suggestion-preview.png)

NOTE: **Note:**
438 439 440
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.
Oswaldo Ferreira's avatar
Oswaldo Ferreira committed
441

442 443 444
### Configure the commit message for applied Suggestions

> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/13086) in GitLab 12.7.
445

446 447 448 449 450
GitLab uses `Apply suggestion to %{file_path}` by default as commit messages
when applying Suggestions. This commit message can be customized to
follow any guidelines you might have. To do so, expand the **Merge requests**
tab within your project's **General** settings and change the
**Merge suggestions** text:
451

452
![Custom commit message for applied Suggestions](img/suggestions_custom_commit_messages_v12_7.png)
453 454 455

You can also use following variables besides static text:

456 457 458 459 460 461 462
| Variable | Description | Output example |
|---|---|---|
| `%{project_path}` | The project path. | `my-group/my-project` |
| `%{project_name}` | The human-readable name of the project. | **My Project** |
| `%{file_path}` | The path of the file the Suggestion is applied to. | `docs/index.md` |
| `%{branch_name}` | The name of the branch the Suggestion is applied on. | `my-feature-branch` |
| `%{username}` | The username of the user applying the Suggestion. | `user_1` |
463
| `%{user_full_name}` | The full name of the user applying the Suggestion. | **User 1** |
464 465 466

For example, to customize the commit message to output
**Addresses user_1's review**, set the custom text to
467
`Addresses %{username}'s review`.
468 469 470 471

NOTE: **Note:**
Custom commit messages for each applied Suggestion will be
introduced by [#25381](https://gitlab.com/gitlab-org/gitlab/issues/25381).
472

473
## Start a thread by replying to a standard comment
474

475
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/30299) in GitLab 11.9
476

477
To reply to a standard (non-thread) comment, you can use the **Reply to comment** button.
478 479 480

![Reply to comment button](img/reply_to_comment_button.png)

481
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.
482 483 484 485 486

Clicking on the **Reply to comment** button will bring the reply area into focus and you can type your reply.

![Reply to comment feature](img/reply_to_comment.gif)

487 488
Replying to a non-thread comment will convert the non-thread comment to a
thread once the reply is submitted. This conversion is considered an edit
489
to the original comment, so a note about when it was last edited will appear underneath it.
490

491
This feature only exists for Issues, Merge requests, and Epics. Commits, Snippets and Merge request diff threads are
492
not supported yet.
493

494 495 496 497 498 499 500 501
[ce-7125]: https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/7125
[ce-7527]: https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/7527
[ce-7180]: https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/7180
[ce-8266]: https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/8266
[ce-14053]: https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/14053
[ce-14061]: https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/14061
[ce-14531]: https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/14531
[ce-31847]: https://gitlab.com/gitlab-org/gitlab-foss/issues/31847
502 503 504 505 506
[resolve-discussion-button]: img/resolve_discussion_button.png
[resolve-comment-button]: img/resolve_comment_button.png
[discussion-view]: img/discussion_view.png
[discussions-resolved]: img/discussions_resolved.png
[markdown]: ../markdown.md
507
[quick actions]: ../project/quick_actions.md
508
[permissions]: ../permissions.md
509
[Reply by email]: ../../administration/reply_by_email.md