diff options
Diffstat (limited to 'doc/user/discussions')
15 files changed, 150 insertions, 0 deletions
diff --git a/doc/user/discussions/img/btn_new_issue_for_all_discussions.png b/doc/user/discussions/img/btn_new_issue_for_all_discussions.png Binary files differnew file mode 100644 index 00000000000..b15447ec290 --- /dev/null +++ b/doc/user/discussions/img/btn_new_issue_for_all_discussions.png diff --git a/doc/user/discussions/img/comment_type_toggle.gif b/doc/user/discussions/img/comment_type_toggle.gif Binary files differnew file mode 100644 index 00000000000..b73c197b97f --- /dev/null +++ b/doc/user/discussions/img/comment_type_toggle.gif diff --git a/doc/user/discussions/img/discussion_comment.png b/doc/user/discussions/img/discussion_comment.png Binary files differnew file mode 100644 index 00000000000..8f66d138922 --- /dev/null +++ b/doc/user/discussions/img/discussion_comment.png diff --git a/doc/user/discussions/img/discussion_view.png b/doc/user/discussions/img/discussion_view.png Binary files differnew file mode 100644 index 00000000000..2ee1db2eab3 --- /dev/null +++ b/doc/user/discussions/img/discussion_view.png diff --git a/doc/user/discussions/img/discussions_resolved.png b/doc/user/discussions/img/discussions_resolved.png Binary files differnew file mode 100644 index 00000000000..3fd496f6da5 --- /dev/null +++ b/doc/user/discussions/img/discussions_resolved.png diff --git a/doc/user/discussions/img/new_issue_for_discussion.png b/doc/user/discussions/img/new_issue_for_discussion.png Binary files differnew file mode 100644 index 00000000000..93c9dad8921 --- /dev/null +++ b/doc/user/discussions/img/new_issue_for_discussion.png diff --git a/doc/user/discussions/img/only_allow_merge_if_all_discussions_are_resolved.png b/doc/user/discussions/img/only_allow_merge_if_all_discussions_are_resolved.png Binary files differnew file mode 100644 index 00000000000..928c7d33898 --- /dev/null +++ b/doc/user/discussions/img/only_allow_merge_if_all_discussions_are_resolved.png diff --git a/doc/user/discussions/img/only_allow_merge_if_all_discussions_are_resolved_msg.png b/doc/user/discussions/img/only_allow_merge_if_all_discussions_are_resolved_msg.png Binary files differnew file mode 100644 index 00000000000..bcdc0250d7c --- /dev/null +++ b/doc/user/discussions/img/only_allow_merge_if_all_discussions_are_resolved_msg.png diff --git a/doc/user/discussions/img/preview_issue_for_discussion.png b/doc/user/discussions/img/preview_issue_for_discussion.png Binary files differnew file mode 100644 index 00000000000..2ee0653b2ba --- /dev/null +++ b/doc/user/discussions/img/preview_issue_for_discussion.png diff --git a/doc/user/discussions/img/preview_issue_for_discussions.png b/doc/user/discussions/img/preview_issue_for_discussions.png Binary files differnew file mode 100644 index 00000000000..3fe0a666678 --- /dev/null +++ b/doc/user/discussions/img/preview_issue_for_discussions.png diff --git a/doc/user/discussions/img/resolve_comment_button.png b/doc/user/discussions/img/resolve_comment_button.png Binary files differnew file mode 100644 index 00000000000..70340108874 --- /dev/null +++ b/doc/user/discussions/img/resolve_comment_button.png diff --git a/doc/user/discussions/img/resolve_discussion_button.png b/doc/user/discussions/img/resolve_discussion_button.png Binary files differnew file mode 100644 index 00000000000..ab454f661e0 --- /dev/null +++ b/doc/user/discussions/img/resolve_discussion_button.png diff --git a/doc/user/discussions/img/resolve_discussion_issue_notice.png b/doc/user/discussions/img/resolve_discussion_issue_notice.png Binary files differnew file mode 100644 index 00000000000..e0ee6a39ffd --- /dev/null +++ b/doc/user/discussions/img/resolve_discussion_issue_notice.png diff --git a/doc/user/discussions/img/resolve_discussion_open_issue.png b/doc/user/discussions/img/resolve_discussion_open_issue.png Binary files differnew file mode 100644 index 00000000000..98d63278326 --- /dev/null +++ b/doc/user/discussions/img/resolve_discussion_open_issue.png diff --git a/doc/user/discussions/index.md b/doc/user/discussions/index.md new file mode 100644 index 00000000000..59e343ebe51 --- /dev/null +++ b/doc/user/discussions/index.md @@ -0,0 +1,150 @@ +# Discussions + +The ability to contribute conversationally is offered throughout GitLab. + +You can leave a comment in the following places: + +- issues +- merge requests +- snippets +- commits +- commit diffs + +The comment area supports [Markdown] and [slash commands]. One can edit their +own comment at any time, and anyone with [Master 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. + +## Resolvable 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] + +Comments and discussions can be resolved by anyone with at least Developer +access to the project or the author of the merge request. + +### 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] + +### Marking a comment or discussion as resolved + +You can mark a discussion as resolved by clicking the **Resolve discussion** +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] + +### Move all unresolved discussions in a merge request to an issue + +> [Introduced][ce-8266] in GitLab 9.1 + +To continue all open discussions from a merge request in a new issue, click the +**Resolve all discussions in new issue** button. + +![Open new issue for all unresolved discussions](img/btn_new_issue_for_all_discussions.png) + +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. + +![Link in merge request widget](img/resolve_discussion_open_issue.png) + +This will prepare an issue with its content referring to the merge request and +the unresolved discussions. + +![Issue mentioning discussions in a merge request](img/preview_issue_for_discussions.png) + +Hitting **Submit issue** will cause all discussions to be marked as resolved and +add a note referring to the newly created issue. + +![Mark discussions as resolved notice](img/resolve_discussion_issue_notice.png) + +You can now proceed to merge the merge request from the UI. + +### Moving a single discussion to a new issue + +> [Introduced][ce-8266] in GitLab 9.1 + +To create a new issue for a single discussion, you can use the **Resolve this +discussion in a new issue** button. + +![Create issue for discussion](img/new_issue_for_discussion.png) + +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) + +### Only allow merge requests to be merged if all discussions are resolved + +> [Introduced][ce-7125] in GitLab 8.14. + +You can prevent merge requests from being merged until all discussions are +resolved. + +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) + +## Threaded discussions + +> [Introduced][ce-7527] in GitLab 9.1. + +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. + +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. + +![Comment type toggle](img/comment_type_toggle.gif) + +This will post a comment with a single thread to allow you to discuss specific +comments in greater detail. + +![Discussion comment](img/discussion_comment.png) + +[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 +[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 +[slash commands]: ../project/slash_commands.md +[permissions]: ../permissions.md |