diff options
author | Achilleas Pipinellis <axilleas@axilleas.me> | 2017-04-21 21:43:40 +0300 |
---|---|---|
committer | Achilleas Pipinellis <axilleas@axilleas.me> | 2017-04-21 21:43:40 +0300 |
commit | 5aea8c4fa46fdd3caf3b65560c9b2d744421b8db (patch) | |
tree | e95b13bc57d0d33959ded40975ec972580f936b4 /doc | |
parent | 9c35162f83fb62349b922baaf192038522b09793 (diff) | |
parent | e84787ae085e184c893f7da40ca29a0c5fecf810 (diff) |
Merge branch 'resolvable-discussions-docs' into 'master'
discussions docs
See merge request !10390
Diffstat (limited to 'doc')
-rw-r--r-- | doc/README.md | 1 | ||||
-rw-r--r-- | doc/user/discussions/img/btn_new_issue_for_all_discussions.png (renamed from doc/user/project/merge_requests/img/btn_new_issue_for_all_discussions.png) | bin | 29007 -> 29007 bytes | |||
-rw-r--r-- | doc/user/discussions/img/comment_type_toggle.gif | bin | 0 -> 70796 bytes | |||
-rw-r--r-- | doc/user/discussions/img/discussion_comment.png | bin | 0 -> 57189 bytes | |||
-rw-r--r-- | doc/user/discussions/img/discussion_view.png (renamed from doc/user/project/merge_requests/img/discussion_view.png) | bin | 73821 -> 73821 bytes | |||
-rw-r--r-- | doc/user/discussions/img/discussions_resolved.png (renamed from doc/user/project/merge_requests/img/discussions_resolved.png) | bin | 4152 -> 4152 bytes | |||
-rw-r--r-- | doc/user/discussions/img/new_issue_for_discussion.png (renamed from doc/user/project/merge_requests/img/new_issue_for_discussion.png) | bin | 39563 -> 39563 bytes | |||
-rw-r--r-- | doc/user/discussions/img/only_allow_merge_if_all_discussions_are_resolved.png (renamed from doc/user/project/merge_requests/img/only_allow_merge_if_all_discussions_are_resolved.png) | bin | 17888 -> 17888 bytes | |||
-rw-r--r-- | doc/user/discussions/img/only_allow_merge_if_all_discussions_are_resolved_msg.png (renamed from doc/user/project/merge_requests/img/only_allow_merge_if_all_discussions_are_resolved_msg.png) | bin | 4962 -> 4962 bytes | |||
-rw-r--r-- | doc/user/discussions/img/preview_issue_for_discussion.png (renamed from doc/user/project/merge_requests/img/preview_issue_for_discussion.png) | bin | 82412 -> 82412 bytes | |||
-rw-r--r-- | doc/user/discussions/img/preview_issue_for_discussions.png (renamed from doc/user/project/merge_requests/img/preview_issue_for_discussions.png) | bin | 143871 -> 143871 bytes | |||
-rw-r--r-- | doc/user/discussions/img/resolve_comment_button.png (renamed from doc/user/project/merge_requests/img/resolve_comment_button.png) | bin | 4722 -> 4722 bytes | |||
-rw-r--r-- | doc/user/discussions/img/resolve_discussion_button.png (renamed from doc/user/project/merge_requests/img/resolve_discussion_button.png) | bin | 4683 -> 4683 bytes | |||
-rw-r--r-- | doc/user/discussions/img/resolve_discussion_issue_notice.png (renamed from doc/user/project/merge_requests/img/resolve_discussion_issue_notice.png) | bin | 10307 -> 10307 bytes | |||
-rw-r--r-- | doc/user/discussions/img/resolve_discussion_open_issue.png (renamed from doc/user/project/merge_requests/img/resolve_discussion_open_issue.png) | bin | 20967 -> 20967 bytes | |||
-rw-r--r-- | doc/user/discussions/index.md | 150 | ||||
-rw-r--r-- | doc/user/project/merge_requests/index.md | 2 | ||||
-rw-r--r-- | doc/user/project/merge_requests/merge_request_discussion_resolution.md | 107 | ||||
-rw-r--r-- | doc/workflow/README.md | 2 |
19 files changed, 154 insertions, 108 deletions
diff --git a/doc/README.md b/doc/README.md index 9e6a5b4ed44..fb393aa09a1 100644 --- a/doc/README.md +++ b/doc/README.md @@ -15,6 +15,7 @@ All technical content published by GitLab lives in the documentation, including: - [API](api/README.md) Automate GitLab via a simple and powerful API. - [CI/CD](ci/README.md) GitLab Continuous Integration (CI) and Continuous Delivery (CD) getting started, `.gitlab-ci.yml` options, and examples. - [Container Registry](user/project/container_registry.md) Learn how to use GitLab Container Registry. +- [Discussions](user/discussions/index.md) Threads, comments, and resolvable discussions in issues, commits, and merge requests. - [Git Attributes](user/project/git_attributes.md) Managing Git attributes using a `.gitattributes` file. - [Git cheatsheet](https://gitlab.com/gitlab-com/marketing/raw/master/design/print/git-cheatsheet/print-pdf/git-cheatsheet.pdf) Download a PDF describing the most used Git operations. - [GitLab as OAuth2 authentication service provider](integration/oauth_provider.md). It allows you to login to other applications from GitLab. diff --git a/doc/user/project/merge_requests/img/btn_new_issue_for_all_discussions.png b/doc/user/discussions/img/btn_new_issue_for_all_discussions.png Binary files differindex b15447ec290..b15447ec290 100644 --- a/doc/user/project/merge_requests/img/btn_new_issue_for_all_discussions.png +++ 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/project/merge_requests/img/discussion_view.png b/doc/user/discussions/img/discussion_view.png Binary files differindex 2ee1db2eab3..2ee1db2eab3 100644 --- a/doc/user/project/merge_requests/img/discussion_view.png +++ b/doc/user/discussions/img/discussion_view.png diff --git a/doc/user/project/merge_requests/img/discussions_resolved.png b/doc/user/discussions/img/discussions_resolved.png Binary files differindex 3fd496f6da5..3fd496f6da5 100644 --- a/doc/user/project/merge_requests/img/discussions_resolved.png +++ b/doc/user/discussions/img/discussions_resolved.png diff --git a/doc/user/project/merge_requests/img/new_issue_for_discussion.png b/doc/user/discussions/img/new_issue_for_discussion.png Binary files differindex 93c9dad8921..93c9dad8921 100644 --- a/doc/user/project/merge_requests/img/new_issue_for_discussion.png +++ b/doc/user/discussions/img/new_issue_for_discussion.png diff --git a/doc/user/project/merge_requests/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 differindex 928c7d33898..928c7d33898 100644 --- a/doc/user/project/merge_requests/img/only_allow_merge_if_all_discussions_are_resolved.png +++ b/doc/user/discussions/img/only_allow_merge_if_all_discussions_are_resolved.png diff --git a/doc/user/project/merge_requests/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 differindex bcdc0250d7c..bcdc0250d7c 100644 --- a/doc/user/project/merge_requests/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 diff --git a/doc/user/project/merge_requests/img/preview_issue_for_discussion.png b/doc/user/discussions/img/preview_issue_for_discussion.png Binary files differindex 2ee0653b2ba..2ee0653b2ba 100644 --- a/doc/user/project/merge_requests/img/preview_issue_for_discussion.png +++ b/doc/user/discussions/img/preview_issue_for_discussion.png diff --git a/doc/user/project/merge_requests/img/preview_issue_for_discussions.png b/doc/user/discussions/img/preview_issue_for_discussions.png Binary files differindex 3fe0a666678..3fe0a666678 100644 --- a/doc/user/project/merge_requests/img/preview_issue_for_discussions.png +++ b/doc/user/discussions/img/preview_issue_for_discussions.png diff --git a/doc/user/project/merge_requests/img/resolve_comment_button.png b/doc/user/discussions/img/resolve_comment_button.png Binary files differindex 70340108874..70340108874 100644 --- a/doc/user/project/merge_requests/img/resolve_comment_button.png +++ b/doc/user/discussions/img/resolve_comment_button.png diff --git a/doc/user/project/merge_requests/img/resolve_discussion_button.png b/doc/user/discussions/img/resolve_discussion_button.png Binary files differindex ab454f661e0..ab454f661e0 100644 --- a/doc/user/project/merge_requests/img/resolve_discussion_button.png +++ b/doc/user/discussions/img/resolve_discussion_button.png diff --git a/doc/user/project/merge_requests/img/resolve_discussion_issue_notice.png b/doc/user/discussions/img/resolve_discussion_issue_notice.png Binary files differindex e0ee6a39ffd..e0ee6a39ffd 100644 --- a/doc/user/project/merge_requests/img/resolve_discussion_issue_notice.png +++ b/doc/user/discussions/img/resolve_discussion_issue_notice.png diff --git a/doc/user/project/merge_requests/img/resolve_discussion_open_issue.png b/doc/user/discussions/img/resolve_discussion_open_issue.png Binary files differindex 98d63278326..98d63278326 100644 --- a/doc/user/project/merge_requests/img/resolve_discussion_open_issue.png +++ 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..c5123c06ce0 --- /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 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 diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index c759b7aaa4a..954454f7e7a 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -34,7 +34,7 @@ Keep track of the progress during a code review with resolving comments. Resolving comments prevents you from forgetting to address feedback and lets you hide discussions that are no longer relevant. -[Read more about resolving discussion comments in merge requests reviews.](merge_request_discussion_resolution.md) +[Read more about resolving discussion comments in merge requests reviews.](../../discussions/index.md) ## Resolve conflicts diff --git a/doc/user/project/merge_requests/merge_request_discussion_resolution.md b/doc/user/project/merge_requests/merge_request_discussion_resolution.md index 230e957f045..200965875a1 100644 --- a/doc/user/project/merge_requests/merge_request_discussion_resolution.md +++ b/doc/user/project/merge_requests/merge_request_discussion_resolution.md @@ -1,106 +1 @@ -# Merge Request discussion resolution - -> [Introduced][ce-5022] in GitLab 8.11. - -Discussion resolution helps keep track of progress during 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, as well as by the author of the merge request. - -## 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] - -## 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] - -## 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) - -## Move all unresolved discussions in a merge request to an issue - -> [Introduced][ce-8266] - -To continue all open discussions in a merge request, click the button **Resolve -all discussions in new issue** - -![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, 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 content referring to the merge request and -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] - -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. - -![New issue for a single discussion](img/preview_issue_for_discussion.png) - -Saving the issue will mark the discussion as resolved and add a note -to the discussion referencing the new issue. - -[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-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 +This document was moved to [another location](../../discussions/index.md). diff --git a/doc/workflow/README.md b/doc/workflow/README.md index 375b334c3b6..604c7d5cefb 100644 --- a/doc/workflow/README.md +++ b/doc/workflow/README.md @@ -32,7 +32,7 @@ - [Authorization for merge requests](../user/project/merge_requests/authorization_for_merge_requests.md) - [Cherry-pick changes](../user/project/merge_requests/cherry_pick_changes.md) - [Merge when pipeline succeeds](../user/project/merge_requests/merge_when_pipeline_succeeds.md) - - [Resolve discussion comments in merge requests reviews](../user/project/merge_requests/merge_request_discussion_resolution.md) + - [Resolve discussion comments in merge requests reviews](../user/discussions/index.md) - [Resolve merge conflicts in the UI](../user/project/merge_requests/resolve_conflicts.md) - [Revert changes in the UI](../user/project/merge_requests/revert_changes.md) - [Merge requests versions](../user/project/merge_requests/versions.md) |