2017-04-01 09:45:17 +00:00
|
|
|
# Discussions
|
2016-08-16 22:05:10 +00:00
|
|
|
|
2017-04-01 09:45:17 +00:00
|
|
|
The ability to contribute conversationally is offered throughout GitLab.
|
|
|
|
|
2017-04-21 17:35:23 +00:00
|
|
|
You can leave a comment in the following places:
|
2017-04-01 09:45:17 +00:00
|
|
|
|
2017-04-21 17:35:23 +00:00
|
|
|
- issues
|
|
|
|
- merge requests
|
|
|
|
- snippets
|
|
|
|
- commits
|
|
|
|
- commit diffs
|
2017-04-01 09:45:17 +00:00
|
|
|
|
2017-05-31 05:50:53 +00:00
|
|
|
The comment area supports [Markdown] and [quick actions]. One can edit their
|
2018-05-22 10:16:06 +00:00
|
|
|
own comment at any time, and anyone with [Maintainer access level][permissions] or
|
2017-04-24 16:39:47 +00:00
|
|
|
higher can also edit a comment made by someone else.
|
2016-08-16 22:05:10 +00:00
|
|
|
|
2018-04-11 10:17:28 +00:00
|
|
|
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.
|
|
|
|
|
2017-04-21 17:35:23 +00:00
|
|
|
Apart from the standard comments, you also have the option to create a comment
|
|
|
|
in the form of a resolvable or threaded discussion.
|
|
|
|
|
|
|
|
## Resolvable discussions
|
|
|
|
|
2018-09-06 16:52:18 +00:00
|
|
|
> **Notes:**
|
|
|
|
> - The main feature was [introduced][ce-5022] in GitLab 8.11.
|
|
|
|
> - Resolvable discussions can be added only to merge request diffs.
|
2017-04-01 09:45:17 +00:00
|
|
|
|
|
|
|
Discussion resolution helps keep track of progress during planning or code review.
|
2016-08-16 22:05:10 +00:00
|
|
|
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]
|
|
|
|
|
|
|
|
Comments and discussions can be resolved by anyone with at least Developer
|
2017-04-01 09:45:17 +00:00
|
|
|
access to the project or the author of the merge request.
|
2016-08-16 22:05:10 +00:00
|
|
|
|
2017-12-12 15:53:52 +00:00
|
|
|
### Commit discussions in the context of a merge request
|
|
|
|
|
|
|
|
> [Introduced][ce-31847] in GitLab 10.3.
|
|
|
|
|
|
|
|
For reviewers with commit-based workflow, it may be useful to add discussions to
|
|
|
|
specific commit diffs in the context of a merge request. These discussions will
|
|
|
|
persist through a commit ID change when:
|
|
|
|
|
|
|
|
- force-pushing after a rebase
|
|
|
|
- amending a commit
|
|
|
|
|
|
|
|
To create a commit diff discussion:
|
|
|
|
|
|
|
|
1. Navigate to the merge request **Commits** tab. A list of commits that
|
|
|
|
constitute the merge request will be shown.
|
|
|
|
|
|
|
|
![Merge request commits tab](img/merge_request_commits_tab.png)
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
![Commit diff discussion in merge request context](img/commit_comment_mr_context.png)
|
|
|
|
|
|
|
|
1. Any discussions created this way will be shown in the merge request's
|
|
|
|
**Discussions** tab and are resolvable.
|
|
|
|
|
|
|
|
![Merge request Discussions tab](img/commit_comment_mr_discussions_tab.png)
|
|
|
|
|
|
|
|
Discussions created this way will only appear in the original merge request
|
|
|
|
and not when navigating to that commit under your project's
|
|
|
|
**Repository > Commits** page.
|
|
|
|
|
|
|
|
TIP: **Tip:**
|
|
|
|
When a link of a commit reference is found in a discussion inside a merge
|
|
|
|
request, it will be automatically converted to a link in the context of the
|
|
|
|
current merge request.
|
|
|
|
|
2017-04-21 17:35:23 +00:00
|
|
|
### Jumping between unresolved discussions
|
|
|
|
|
|
|
|
When a merge request has a large number of comments it can be difficult to track
|
|
|
|
what remains unresolved. You can jump between unresolved discussions with the
|
|
|
|
Jump button next to the Reply field on a discussion.
|
|
|
|
|
|
|
|
You can also jump to the first unresolved discussion from the button next to the
|
|
|
|
resolved discussions tracker.
|
|
|
|
|
|
|
|
!["3/4 discussions resolved"][discussions-resolved]
|
|
|
|
|
2017-04-01 09:45:17 +00:00
|
|
|
### Marking a comment or discussion as resolved
|
2016-08-16 22:05:10 +00:00
|
|
|
|
2017-04-21 17:35:23 +00:00
|
|
|
You can mark a discussion as resolved by clicking the **Resolve discussion**
|
2016-08-16 22:05:10 +00:00
|
|
|
button at the bottom of the discussion.
|
|
|
|
|
|
|
|
!["Resolve discussion" button][resolve-discussion-button]
|
|
|
|
|
|
|
|
Alternatively, you can mark each comment as resolved individually.
|
|
|
|
|
|
|
|
!["Resolve comment" button][resolve-comment-button]
|
|
|
|
|
2017-04-21 17:35:23 +00:00
|
|
|
### Move all unresolved discussions in a merge request to an issue
|
2017-04-01 09:45:17 +00:00
|
|
|
|
|
|
|
> [Introduced][ce-8266] in GitLab 9.1
|
|
|
|
|
2017-04-21 17:35:23 +00:00
|
|
|
To continue all open discussions from a merge request in a new issue, click the
|
|
|
|
**Resolve all discussions in new issue** button.
|
2017-04-01 09:45:17 +00:00
|
|
|
|
2017-04-21 17:35:23 +00:00
|
|
|
![Open new issue for all unresolved discussions](img/btn_new_issue_for_all_discussions.png)
|
2017-04-01 09:45:17 +00:00
|
|
|
|
2017-04-21 17:35:23 +00:00
|
|
|
Alternatively, when your project only accepts merge requests [when all discussions
|
|
|
|
are resolved](#only-allow-merge-requests-to-be-merged-if-all-discussions-are-resolved),
|
|
|
|
there will be an **open an issue to resolve them later** link in the merge
|
|
|
|
request widget.
|
2017-04-01 09:45:17 +00:00
|
|
|
|
2017-04-21 17:35:23 +00:00
|
|
|
![Link in merge request widget](img/resolve_discussion_open_issue.png)
|
2017-04-01 09:45:17 +00:00
|
|
|
|
2017-04-21 17:35:23 +00:00
|
|
|
This will prepare an issue with its content referring to the merge request and
|
|
|
|
the unresolved discussions.
|
2017-04-01 09:45:17 +00:00
|
|
|
|
2017-04-21 17:35:23 +00:00
|
|
|
![Issue mentioning discussions in a merge request](img/preview_issue_for_discussions.png)
|
2017-04-01 09:45:17 +00:00
|
|
|
|
2017-04-21 17:35:23 +00:00
|
|
|
Hitting **Submit issue** will cause all discussions to be marked as resolved and
|
|
|
|
add a note referring to the newly created issue.
|
2017-04-01 09:45:17 +00:00
|
|
|
|
2017-04-21 17:35:23 +00:00
|
|
|
![Mark discussions as resolved notice](img/resolve_discussion_issue_notice.png)
|
2017-04-01 09:45:17 +00:00
|
|
|
|
2017-04-21 17:35:23 +00:00
|
|
|
You can now proceed to merge the merge request from the UI.
|
2017-04-01 09:45:17 +00:00
|
|
|
|
2017-04-21 17:35:23 +00:00
|
|
|
### Moving a single discussion to a new issue
|
2017-04-01 09:45:17 +00:00
|
|
|
|
2017-04-21 17:35:23 +00:00
|
|
|
> [Introduced][ce-8266] in GitLab 9.1
|
2016-08-16 22:05:10 +00:00
|
|
|
|
2017-04-21 17:35:23 +00:00
|
|
|
To create a new issue for a single discussion, you can use the **Resolve this
|
|
|
|
discussion in a new issue** button.
|
2016-08-16 22:05:10 +00:00
|
|
|
|
2017-04-21 17:35:23 +00:00
|
|
|
![Create issue for discussion](img/new_issue_for_discussion.png)
|
2016-08-16 22:05:10 +00:00
|
|
|
|
2017-04-21 17:35:23 +00:00
|
|
|
This will direct you to a new issue prefilled with the content of the
|
|
|
|
discussion, similar to the issues created for delegating multiple
|
|
|
|
discussions at once. Saving the issue will mark the discussion as resolved and
|
|
|
|
add a note to the merge request discussion referencing the new issue.
|
|
|
|
|
|
|
|
![New issue for a single discussion](img/preview_issue_for_discussion.png)
|
2016-08-16 22:05:10 +00:00
|
|
|
|
2017-04-01 09:45:17 +00:00
|
|
|
### Only allow merge requests to be merged if all discussions are resolved
|
2016-10-31 15:00:42 +00:00
|
|
|
|
|
|
|
> [Introduced][ce-7125] in GitLab 8.14.
|
|
|
|
|
2016-10-26 21:21:50 +00:00
|
|
|
You can prevent merge requests from being merged until all discussions are
|
|
|
|
resolved.
|
2016-10-31 15:00:42 +00:00
|
|
|
|
|
|
|
Navigate to your project's settings page, select the
|
|
|
|
**Only allow merge requests to be merged if all discussions are resolved** check
|
|
|
|
box and hit **Save** for the changes to take effect.
|
|
|
|
|
|
|
|
![Only allow merge if all the discussions are resolved settings](img/only_allow_merge_if_all_discussions_are_resolved.png)
|
|
|
|
|
|
|
|
From now on, you will not be able to merge from the UI until all discussions
|
|
|
|
are resolved.
|
|
|
|
|
|
|
|
![Only allow merge if all the discussions are resolved message](img/only_allow_merge_if_all_discussions_are_resolved_msg.png)
|
|
|
|
|
2017-09-05 15:49:05 +00:00
|
|
|
### Automatically resolve merge request diff discussions when they become outdated
|
2017-08-28 21:38:06 +00:00
|
|
|
|
2017-09-05 15:49:05 +00:00
|
|
|
> [Introduced][ce-14053] in GitLab 10.0.
|
2017-08-28 21:38:06 +00:00
|
|
|
|
2017-09-05 15:49:05 +00:00
|
|
|
You can automatically resolve merge request diff discussions on lines modified
|
|
|
|
with a new push.
|
|
|
|
|
|
|
|
Navigate to your project's settings page, select the **Automatically resolve
|
|
|
|
merge request diffs discussions on lines changed with a push** check box and hit
|
2017-08-28 21:38:06 +00:00
|
|
|
**Save** for the changes to take effect.
|
|
|
|
|
2017-09-05 15:49:05 +00:00
|
|
|
![Automatically resolve merge request diff discussions when they become outdated](img/automatically_resolve_outdated_discussions.png)
|
2017-08-28 21:38:06 +00:00
|
|
|
|
2017-09-05 15:49:05 +00:00
|
|
|
From now on, any discussions on a diff will be resolved by default if a push
|
|
|
|
makes that diff section outdated. Discussions on lines that don't change and
|
|
|
|
top-level resolvable discussions are not automatically resolved.
|
2017-08-28 21:38:06 +00:00
|
|
|
|
2017-12-12 15:53:52 +00:00
|
|
|
## Commit discussions
|
|
|
|
|
|
|
|
You can add comments and discussion threads to a particular commit under your
|
|
|
|
project's **Repository > Commits**.
|
|
|
|
|
|
|
|
CAUTION: **Attention:**
|
|
|
|
Discussions created this way will be lost if the commit ID changes after a
|
|
|
|
force push.
|
|
|
|
|
2017-04-21 17:35:23 +00:00
|
|
|
## Threaded discussions
|
2016-12-22 12:31:12 +00:00
|
|
|
|
2017-04-01 09:45:17 +00:00
|
|
|
> [Introduced][ce-7527] in GitLab 9.1.
|
2016-12-22 12:31:12 +00:00
|
|
|
|
2017-04-21 17:35:23 +00:00
|
|
|
While resolvable discussions are only available to merge request diffs,
|
|
|
|
discussions can also be added without a diff. You can start a specific
|
|
|
|
discussion which will look like a thread, on issues, commits, snippets, and
|
|
|
|
merge requests.
|
2016-12-22 12:31:12 +00:00
|
|
|
|
2017-04-21 17:35:23 +00:00
|
|
|
To start a threaded discussion, click on the **Comment** button toggle dropdown,
|
|
|
|
select **Start discussion** and click **Start discussion** when you're ready to
|
|
|
|
post the comment.
|
2017-04-07 15:44:02 +00:00
|
|
|
|
|
|
|
![Comment type toggle](img/comment_type_toggle.gif)
|
|
|
|
|
2017-04-21 17:35:23 +00:00
|
|
|
This will post a comment with a single thread to allow you to discuss specific
|
|
|
|
comments in greater detail.
|
2017-04-07 15:44:02 +00:00
|
|
|
|
|
|
|
![Discussion comment](img/discussion_comment.png)
|
2017-04-21 17:35:23 +00:00
|
|
|
|
2017-10-11 06:07:55 +00:00
|
|
|
## Image discussions
|
|
|
|
|
2017-10-11 13:59:01 +00:00
|
|
|
> [Introduced][ce-14061] in GitLab 10.1.
|
2017-10-11 06:07:55 +00:00
|
|
|
|
|
|
|
Sometimes a discussion is revolved around an image. With image discussions,
|
|
|
|
you can easily target a specific coordinate of an image and start a discussion
|
|
|
|
around it. Image discussions are available in merge requests and commit detail views.
|
|
|
|
|
|
|
|
To start an image discussion, 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 discussion.
|
|
|
|
|
|
|
|
![Start image discussion](img/start_image_discussion.gif)
|
|
|
|
|
|
|
|
After you click on the image, a comment form will be displayed that would be the start
|
|
|
|
of your discussion. Once you save your comment, you will see a new badge displayed on
|
|
|
|
top of your image. This badge represents your discussion.
|
|
|
|
|
|
|
|
>**Note:**
|
|
|
|
This discussion badge is typically associated with a number that is only used as a visual
|
|
|
|
reference for each discussion. In the merge request discussion tab,
|
|
|
|
this badge will be indicated with a comment icon since each discussion will render a new
|
|
|
|
image section.
|
|
|
|
|
|
|
|
Image discussions 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 discussion point badges.
|
|
|
|
|
|
|
|
| 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) |
|
|
|
|
|
|
|
|
Image discussions also work well with resolvable discussions. Resolved discussions
|
|
|
|
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.
|
|
|
|
|
|
|
|
![Image resolved discussion](img/image_resolved_discussion.png)
|
|
|
|
|
2017-10-10 17:47:48 +00:00
|
|
|
## Lock discussions
|
2017-10-04 12:09:20 +00:00
|
|
|
|
|
|
|
> [Introduced][ce-14531] in GitLab 10.1.
|
|
|
|
|
2017-10-10 17:47:48 +00:00
|
|
|
For large projects with many contributors, it may be useful to stop discussions
|
|
|
|
in issues or merge requests in these scenarios:
|
2017-10-04 12:09:20 +00:00
|
|
|
|
2017-10-10 17:47:48 +00:00
|
|
|
- The project maintainer has already resolved the discussion and it is not helpful
|
|
|
|
for continued feedback. The project maintainer has already directed new conversation
|
|
|
|
to newer issues or merge requests.
|
2017-10-11 06:07:55 +00:00
|
|
|
- The people participating in the discussion are trolling, abusive, or otherwise
|
|
|
|
being unproductive.
|
2017-10-04 12:09:20 +00:00
|
|
|
|
2018-05-22 10:16:06 +00:00
|
|
|
In these cases, a user with Maintainer permissions or higher in the project can lock (and unlock)
|
2017-10-10 17:47:48 +00:00
|
|
|
an issue or a merge request, using the "Lock" section in the sidebar:
|
2017-10-05 20:24:07 +00:00
|
|
|
|
2017-10-10 17:47:48 +00:00
|
|
|
| Unlock | Lock |
|
2017-10-04 12:09:20 +00:00
|
|
|
| :-----------: | :----------: |
|
|
|
|
| ![Turn off discussion lock](img/turn_off_lock.png) | ![Turn on discussion lock](img/turn_on_lock.png) |
|
|
|
|
|
2017-10-10 17:47:48 +00:00
|
|
|
System notes indicate locking and unlocking.
|
2017-10-04 12:09:20 +00:00
|
|
|
|
|
|
|
![Discussion lock system notes](img/discussion_lock_system_notes.png)
|
|
|
|
|
2017-10-11 06:07:55 +00:00
|
|
|
In a locked issue or merge request, only team members can add new comments and
|
2017-10-10 17:47:48 +00:00
|
|
|
edit existing comments. Non-team members are restricted from adding or editing comments.
|
2017-10-04 12:09:20 +00:00
|
|
|
|
2017-10-10 17:47:48 +00:00
|
|
|
| Team member | Non-team member |
|
2017-10-04 12:09:20 +00:00
|
|
|
| :-----------: | :----------: |
|
|
|
|
| ![Comment form member](img/lock_form_member.png) | ![Comment form non-member](img/lock_form_non_member.png) |
|
|
|
|
|
2018-08-19 19:43:41 +00:00
|
|
|
Additionally locked issues can not be reopened.
|
|
|
|
|
2017-04-21 17:35:23 +00:00
|
|
|
[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
|
|
|
|
[ce-7180]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7180
|
|
|
|
[ce-8266]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8266
|
2017-09-05 15:49:05 +00:00
|
|
|
[ce-14053]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/14053
|
2017-10-11 13:59:01 +00:00
|
|
|
[ce-14061]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/14061
|
2017-10-04 12:09:20 +00:00
|
|
|
[ce-14531]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/14531
|
2017-12-12 15:53:52 +00:00
|
|
|
[ce-31847]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/31847
|
2017-04-21 17:35:23 +00:00
|
|
|
[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
|
2017-05-31 05:50:53 +00:00
|
|
|
[quick actions]: ../project/quick_actions.md
|
2017-04-21 17:35:23 +00:00
|
|
|
[permissions]: ../permissions.md
|
2018-04-11 10:17:28 +00:00
|
|
|
[Reply by email]: ../../administration/reply_by_email.md
|