From e84787ae085e184c893f7da40ca29a0c5fecf810 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Fri, 21 Apr 2017 19:35:23 +0200 Subject: [PATCH] Refactor Discussions docs - Move to dicsussions/index.md - Bring back previous path with a link to new location - Reorder sections --- doc/README.md | 2 +- .../img/btn_new_issue_for_all_discussions.png | Bin .../img/comment_type_toggle.gif | Bin .../img/discussion_comment.png | Bin .../{ => discussions}/img/discussion_view.png | Bin .../img/discussions_resolved.png | Bin .../img/new_issue_for_discussion.png | Bin ..._merge_if_all_discussions_are_resolved.png | Bin ...ge_if_all_discussions_are_resolved_msg.png | Bin .../img/preview_issue_for_discussion.png | Bin .../img/preview_issue_for_discussions.png | Bin .../img/resolve_comment_button.png | Bin .../img/resolve_discussion_button.png | Bin .../img/resolve_discussion_issue_notice.png | Bin .../img/resolve_discussion_open_issue.png | Bin .../{discussions.md => discussions/index.md} | 153 ++++++++++-------- doc/user/project/merge_requests/index.md | 2 +- .../merge_request_discussion_resolution.md | 1 + doc/workflow/README.md | 2 +- 19 files changed, 86 insertions(+), 74 deletions(-) rename doc/user/{ => discussions}/img/btn_new_issue_for_all_discussions.png (100%) rename doc/user/{ => discussions}/img/comment_type_toggle.gif (100%) rename doc/user/{ => discussions}/img/discussion_comment.png (100%) rename doc/user/{ => discussions}/img/discussion_view.png (100%) rename doc/user/{ => discussions}/img/discussions_resolved.png (100%) rename doc/user/{ => discussions}/img/new_issue_for_discussion.png (100%) rename doc/user/{ => discussions}/img/only_allow_merge_if_all_discussions_are_resolved.png (100%) rename doc/user/{ => discussions}/img/only_allow_merge_if_all_discussions_are_resolved_msg.png (100%) rename doc/user/{ => discussions}/img/preview_issue_for_discussion.png (100%) rename doc/user/{ => discussions}/img/preview_issue_for_discussions.png (100%) rename doc/user/{ => discussions}/img/resolve_comment_button.png (100%) rename doc/user/{ => discussions}/img/resolve_discussion_button.png (100%) rename doc/user/{ => discussions}/img/resolve_discussion_issue_notice.png (100%) rename doc/user/{ => discussions}/img/resolve_discussion_open_issue.png (100%) rename doc/user/{discussions.md => discussions/index.md} (65%) create mode 100644 doc/user/project/merge_requests/merge_request_discussion_resolution.md diff --git a/doc/README.md b/doc/README.md index 67deda1eaeb..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. @@ -23,7 +24,6 @@ All technical content published by GitLab lives in the documentation, including: - [Importing and exporting projects between instances](user/project/settings/import_export.md). - [Importing to GitLab](workflow/importing/README.md) Import your projects from GitHub, Bitbucket, GitLab.com, FogBugz and SVN into GitLab. - [Markdown](user/markdown.md) GitLab's advanced formatting system. -- [Discussions](user/discussions.md) Get the most out of your conversations. - [Migrating from SVN](workflow/importing/migrating_from_svn.md) Convert a SVN repository to Git and GitLab. - [Permissions](user/permissions.md) Learn what each role in a project (external/guest/reporter/developer/master/owner) can do. - [Profile Settings](profile/README.md) diff --git a/doc/user/img/btn_new_issue_for_all_discussions.png b/doc/user/discussions/img/btn_new_issue_for_all_discussions.png similarity index 100% rename from doc/user/img/btn_new_issue_for_all_discussions.png rename to doc/user/discussions/img/btn_new_issue_for_all_discussions.png diff --git a/doc/user/img/comment_type_toggle.gif b/doc/user/discussions/img/comment_type_toggle.gif similarity index 100% rename from doc/user/img/comment_type_toggle.gif rename to doc/user/discussions/img/comment_type_toggle.gif diff --git a/doc/user/img/discussion_comment.png b/doc/user/discussions/img/discussion_comment.png similarity index 100% rename from doc/user/img/discussion_comment.png rename to doc/user/discussions/img/discussion_comment.png diff --git a/doc/user/img/discussion_view.png b/doc/user/discussions/img/discussion_view.png similarity index 100% rename from doc/user/img/discussion_view.png rename to doc/user/discussions/img/discussion_view.png diff --git a/doc/user/img/discussions_resolved.png b/doc/user/discussions/img/discussions_resolved.png similarity index 100% rename from doc/user/img/discussions_resolved.png rename to doc/user/discussions/img/discussions_resolved.png diff --git a/doc/user/img/new_issue_for_discussion.png b/doc/user/discussions/img/new_issue_for_discussion.png similarity index 100% rename from doc/user/img/new_issue_for_discussion.png rename to doc/user/discussions/img/new_issue_for_discussion.png diff --git a/doc/user/img/only_allow_merge_if_all_discussions_are_resolved.png b/doc/user/discussions/img/only_allow_merge_if_all_discussions_are_resolved.png similarity index 100% rename from doc/user/img/only_allow_merge_if_all_discussions_are_resolved.png rename to doc/user/discussions/img/only_allow_merge_if_all_discussions_are_resolved.png diff --git a/doc/user/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 similarity index 100% rename from doc/user/img/only_allow_merge_if_all_discussions_are_resolved_msg.png rename to doc/user/discussions/img/only_allow_merge_if_all_discussions_are_resolved_msg.png diff --git a/doc/user/img/preview_issue_for_discussion.png b/doc/user/discussions/img/preview_issue_for_discussion.png similarity index 100% rename from doc/user/img/preview_issue_for_discussion.png rename to doc/user/discussions/img/preview_issue_for_discussion.png diff --git a/doc/user/img/preview_issue_for_discussions.png b/doc/user/discussions/img/preview_issue_for_discussions.png similarity index 100% rename from doc/user/img/preview_issue_for_discussions.png rename to doc/user/discussions/img/preview_issue_for_discussions.png diff --git a/doc/user/img/resolve_comment_button.png b/doc/user/discussions/img/resolve_comment_button.png similarity index 100% rename from doc/user/img/resolve_comment_button.png rename to doc/user/discussions/img/resolve_comment_button.png diff --git a/doc/user/img/resolve_discussion_button.png b/doc/user/discussions/img/resolve_discussion_button.png similarity index 100% rename from doc/user/img/resolve_discussion_button.png rename to doc/user/discussions/img/resolve_discussion_button.png diff --git a/doc/user/img/resolve_discussion_issue_notice.png b/doc/user/discussions/img/resolve_discussion_issue_notice.png similarity index 100% rename from doc/user/img/resolve_discussion_issue_notice.png rename to doc/user/discussions/img/resolve_discussion_issue_notice.png diff --git a/doc/user/img/resolve_discussion_open_issue.png b/doc/user/discussions/img/resolve_discussion_open_issue.png similarity index 100% rename from doc/user/img/resolve_discussion_open_issue.png rename to doc/user/discussions/img/resolve_discussion_open_issue.png diff --git a/doc/user/discussions.md b/doc/user/discussions/index.md similarity index 65% rename from doc/user/discussions.md rename to doc/user/discussions/index.md index 2276bf1971e..c5123c06ce0 100644 --- a/doc/user/discussions.md +++ b/doc/user/discussions/index.md @@ -2,13 +2,26 @@ The ability to contribute conversationally is offered throughout GitLab. -## Standard Comments +You can leave a comment in the following places: -Standard comments can be added to issues, merge requests, snippets, commits and commit diffs. +- issues +- merge requests +- snippets +- commits +- commit diffs -## Resolvable Discussions +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. -Resolvable discussions can be added to merge request diffs, merge requests, issues, commits and snippets. +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 @@ -19,9 +32,20 @@ hide discussions that are no longer relevant. 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" +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] @@ -30,6 +54,34 @@ 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 @@ -41,41 +93,11 @@ discussion in a new issue** button. 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. +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) -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 - -## Merge request diffs - -> [Introduced][ce-5022] in GitLab 8.11. - -Discussions can be started on merge request diffs to keep track of progress during code review. - -!["A discussion between two people on a piece of code"][discussion-view] - -### 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. @@ -94,46 +116,35 @@ 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] in GitLab 9.1 - -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. - - -## Issues, commits, snippets and merge requests +## Threaded discussions > [Introduced][ce-7527] in GitLab 9.1. -Discussions can be started on issues, commits, snippets and merge requests. +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. -Resolvable discussions can be added to merge request diffs, but discussions can also be added without a diff. - -To start a discussion, you can click on the "Comment" button toggle dropdown, select "Start discussion" and click "Start discussion" when you're ready to post the comment. +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. +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 237d7db30fc..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.](../../discussions.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 new file mode 100644 index 00000000000..200965875a1 --- /dev/null +++ b/doc/user/project/merge_requests/merge_request_discussion_resolution.md @@ -0,0 +1 @@ +This document was moved to [another location](../../discussions/index.md). diff --git a/doc/workflow/README.md b/doc/workflow/README.md index edcb03e03b1..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/discussions.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)