From 3ff9662eb05a10bd6babd8889ba714996f877b72 Mon Sep 17 00:00:00 2001 From: Ash Wilson Date: Wed, 9 Jan 2019 15:59:19 -0500 Subject: [PATCH 01/20] Document using a "PullRequestReviewsItem" for review navigation. Co-Authored-By: Vanessa Yuen Co-Authored-By: Katrina Uychaco --- .../003-pull-request-review.md | 64 +++++++++++-------- 1 file changed, 39 insertions(+), 25 deletions(-) diff --git a/docs/feature-requests/003-pull-request-review.md b/docs/feature-requests/003-pull-request-review.md index a045631c5a..e7c7a45d44 100644 --- a/docs/feature-requests/003-pull-request-review.md +++ b/docs/feature-requests/003-pull-request-review.md @@ -26,7 +26,7 @@ Peer review is also a critical part of the path to acceptance for pull requests ![center pane](https://user-images.githubusercontent.com/378023/46985265-75c9fe00-d124-11e8-9b34-572cd1aaf701.png) * Clicking a pull request in the list opens a `PullRequestDetailItem` in the workspace center. - +* Clicking the "Reviews" label or progress bar opens a `PullRequestReviewsItem` in the right dock. ### PullRequestDetailItem @@ -38,14 +38,15 @@ At the top of each `PullRequestDetailItem` is a summary about the pull request, - Overview - Files (**new**) -- Reviews (**new**) - Commits - Build Status -Below the tabs is a "tools bar" for controls to toggle review comments or collapse files. +Below the tabs is a "tools bar" with controls to toggle review comments or collapse files. #### Footer +> TODO: Add "open" button + ![reviews panel](https://user-images.githubusercontent.com/378023/46536010-17ad4780-c8e8-11e8-8338-338bb592efc5.png) A panel at the bottom of the pane shows the progress for resolved review comments. It also has a "Review Changes" button to create a new review. This panel is persistent throughout all sub-views. It allows creating new reviews no matter where you are. Below examples with the existing sub-views: @@ -54,6 +55,7 @@ Overview | Commits | Build Status --- | --- | --- ![overview](https://user-images.githubusercontent.com/378023/46535907-ca30da80-c8e7-11e8-9401-2b8660d56c25.png) | ![commits](https://user-images.githubusercontent.com/378023/46535908-ca30da80-c8e7-11e8-87ca-01637f2554b6.png) | ![build status](https://user-images.githubusercontent.com/378023/46535909-cac97100-c8e7-11e8-8813-47fdaa3ece57.png) +When the pull request is checked out, an "open" button is shown in the review footer. Clicking "open" opens a `PullRequestReviewsItem` for this pull request's review comments as an item in the right workspace dock. ### Files (tab) @@ -70,26 +72,6 @@ Uncollapsed (default) | Collapsed * For large diffs, the files can be collapsed to get a better overview. - -### Reviews (tab) - -Clicking on the "Reviews" tab shows all reviews of a pull request. This is akin to the review summaries that appear on the "Conversation" tab on dotcom. In addition, each review also includes review comments and their diff. - -![reviews](https://user-images.githubusercontent.com/378023/46535563-c81a4c00-c8e6-11e8-9c0b-6ea575556101.png) - -Uncollapsed (default) | Collapsed ---- | --- -![reviews](https://user-images.githubusercontent.com/378023/46535563-c81a4c00-c8e6-11e8-9c0b-6ea575556101.png) | ![collapsed reviews](https://user-images.githubusercontent.com/378023/46926357-62a72780-d06b-11e8-9344-23389d1c727c.png) - -* Comments can be collapsed to get a better overview. -* Reviews get sorted by "urgency". Showing reviews that still need to get adressed at the top: - 1. "recommended" changes - 2. "commented" changes - 3. "no review" (when a reviewer only leaves review comments, but no summary) - 4. "approved" changes - 5. "previous" reviews (when a reviewer made an earlier review and it's now out-dated) -* Within each group, sorting is done by "newest first". - #### Create a new review ##### `+` Button @@ -131,7 +113,39 @@ Clicking "Finish your review" from a comment or clicking "Review Changes" in the * Review comments can be resolved by clicking on the "Resolve conversation" buttons. * If the "reply..." editor has non-whitespace content, it is submitted as a final comment first. -#### Context and navigation +### PullRequestReviewsItem + +This item is opened in the workspace's right dock when the user: + +* Clicks the review progress bar in the GitHub tab. +* Clicks the "open" button on the review summary footer of a `PullRequestDetailItem`. +* Clicks the "<>" button on a review comment in the "Files" tab of a `PullRequestDetailItem`. + +It shows a scrollable view of all of the reviews and comments associated with a specific pull request, + +> TODO: Illustration for the PullRequestReviewsItem + +Reviews are sorted by "urgency," showing reviews that still need to be addressed at the top. Within each group, sorting is done by "newest first". + +1. "recommended" changes +2. "commented" changes +3. "no review" (when a reviewer only leaves review comments, but no summary) +4. "approved" changes +5. "previous" reviews (when a reviewer made an earlier review and it's now out-dated) + +Clicking on a review summary comment expands or collapses the associated review comments. + +Clicking on a review comment opens a `TextEditor` on the corresponding position of the file under review. The clicked review comment is highlighted as the "current" one. + +#### Within an open TextEditor + +If an open `TextEditor` corresponds to a file that has one or more review comments in an open `PullRequestReviewsItem`, gutter and line decorations are added to the lines that match those review comment positions. The "current" one is styled differently to stand out. + +> TODO: Illustrate the "review comment here" gutter and line decorations + +Clicking on the gutter icon reveals the `PullRequestReviewsItem` and highlights that review comment as the "current" one, scrolling to it and expanding its review if necessary. + +### Context and navigation Review comments are shown in 3 different places. The comments themselves have the same functionality, but allow the comment to be seen in a different context, depending on different use cases. For example "reviewing a pull request", "addressing feedback", "editing the entire file". @@ -145,7 +159,7 @@ In order to navigate between comments or switch context, each comment has the fo * Clicking on the `<>` button in a review comment shows the comment in the entire file. If possible, the scroll-position is retained. This allows to quickly get more context about the code. * If the current pull request is not checked out, the `<>` button is disabled, and a tooltip prompts the user to check out the pull request to edit the source. -* Clicking on the "sandwich" button shows the comment under the "Reviews" tab. +* Clicking on the "sandwich" button shows the comment in the corresponding `PullRequestReviewsItem`. * Clicking on the "file-+" button (not shown in above screenshot) shows the comment under the "Files" tab. * The up and down arrow buttons navigate to the next and previous unresolved review comments. * Reaction emoji may be added to each comment with the "emoji" button. Existing emoji reaction tallies are included beneath each comment. From 3bc411e730e7677d9ceacbce20b9ca9834f8c749 Mon Sep 17 00:00:00 2001 From: Ash Wilson Date: Wed, 9 Jan 2019 16:00:17 -0500 Subject: [PATCH 02/20] We actually called it "Files Changed," not "Files" --- docs/feature-requests/003-pull-request-review.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/feature-requests/003-pull-request-review.md b/docs/feature-requests/003-pull-request-review.md index e7c7a45d44..fdc7654fec 100644 --- a/docs/feature-requests/003-pull-request-review.md +++ b/docs/feature-requests/003-pull-request-review.md @@ -57,9 +57,9 @@ Overview | Commits | Build Status When the pull request is checked out, an "open" button is shown in the review footer. Clicking "open" opens a `PullRequestReviewsItem` for this pull request's review comments as an item in the right workspace dock. -### Files (tab) +### Files Changed (tab) -Clicking on the "Files" tab displays the full, multi-file diff associated with the pull request. This is akin to the "Files changed" tab on dotcom. +Clicking on the "Files Changed" tab displays the full, multi-file diff associated with the pull request. This is akin to the "Files changed" tab on dotcom. ![files](https://user-images.githubusercontent.com/378023/46536560-d3bb4200-c8e9-11e8-9764-dca0b84245cf.png) @@ -119,7 +119,7 @@ This item is opened in the workspace's right dock when the user: * Clicks the review progress bar in the GitHub tab. * Clicks the "open" button on the review summary footer of a `PullRequestDetailItem`. -* Clicks the "<>" button on a review comment in the "Files" tab of a `PullRequestDetailItem`. +* Clicks the "<>" button on a review comment in the "Files Changed" tab of a `PullRequestDetailItem`. It shows a scrollable view of all of the reviews and comments associated with a specific pull request, @@ -160,7 +160,7 @@ In order to navigate between comments or switch context, each comment has the fo * Clicking on the `<>` button in a review comment shows the comment in the entire file. If possible, the scroll-position is retained. This allows to quickly get more context about the code. * If the current pull request is not checked out, the `<>` button is disabled, and a tooltip prompts the user to check out the pull request to edit the source. * Clicking on the "sandwich" button shows the comment in the corresponding `PullRequestReviewsItem`. -* Clicking on the "file-+" button (not shown in above screenshot) shows the comment under the "Files" tab. +* Clicking on the "file-+" button (not shown in above screenshot) shows the comment under the "Files Changed" tab. * The up and down arrow buttons navigate to the next and previous unresolved review comments. * Reaction emoji may be added to each comment with the "emoji" button. Existing emoji reaction tallies are included beneath each comment. From 11fb55898d9adf0f48b6121fadfa3a9d0dbd6a0d Mon Sep 17 00:00:00 2001 From: Ash Wilson Date: Wed, 9 Jan 2019 16:07:48 -0500 Subject: [PATCH 03/20] Describe the review summary panel within the "Files Changed" tab Co-Authored-By: Vanessa Yuen Co-Authored-By: Katrina Uychaco --- docs/feature-requests/003-pull-request-review.md | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/docs/feature-requests/003-pull-request-review.md b/docs/feature-requests/003-pull-request-review.md index fdc7654fec..23244c0a45 100644 --- a/docs/feature-requests/003-pull-request-review.md +++ b/docs/feature-requests/003-pull-request-review.md @@ -61,17 +61,24 @@ When the pull request is checked out, an "open" button is shown in the review fo Clicking on the "Files Changed" tab displays the full, multi-file diff associated with the pull request. This is akin to the "Files changed" tab on dotcom. +> TODO: Change "Show review comments" checkbox to an expand/collapse review summaries control + ![files](https://user-images.githubusercontent.com/378023/46536560-d3bb4200-c8e9-11e8-9764-dca0b84245cf.png) -* Diffs are editable. -* Editing the diff is _only_ possible if the pull request branch is checked out and the local branch history has not diverged from the remote branch history. +Clicking on the "Expand review summaries" control in the filter bar reveals an inline panel that displays the summary of each review created on this pull request, including the review's author, the review's current state, its summary comment, and a progress bar showing how many of the review comments associated with this review have been marked as resolved. + +> TODO: Illustrate the "review summary" list panel + +Clicking the checkbox within each review summary block hides or reveals the review summary comments associated with that review in diff on this tab. Clicking the "Collapse review summaries" control conceals the review summary panel again. + +Beneath the review summary panel is the pull request's combined diff. Diffs are editable, but _only_ if the pull request branch is checked out and the local branch history has not diverged incompatibly from the remote branch history. + +For large diffs, the files can be collapsed to get a better overview. Uncollapsed (default) | Collapsed --- | --- ![files](https://user-images.githubusercontent.com/378023/46536560-d3bb4200-c8e9-11e8-9764-dca0b84245cf.png) | ![collapsed files](https://user-images.githubusercontent.com/378023/46931273-7069a680-d085-11e8-9ea7-c96a1772fe27.png) -* For large diffs, the files can be collapsed to get a better overview. - #### Create a new review ##### `+` Button From 4696ec6fff3c236da0101784be4e3f5f6cd5ed34 Mon Sep 17 00:00:00 2001 From: Ash Wilson Date: Wed, 9 Jan 2019 16:45:16 -0500 Subject: [PATCH 04/20] "Review summary list panel" concept --- docs/feature-requests/003-pull-request-review.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/feature-requests/003-pull-request-review.md b/docs/feature-requests/003-pull-request-review.md index 23244c0a45..2eaf6dd336 100644 --- a/docs/feature-requests/003-pull-request-review.md +++ b/docs/feature-requests/003-pull-request-review.md @@ -67,7 +67,7 @@ Clicking on the "Files Changed" tab displays the full, multi-file diff associate Clicking on the "Expand review summaries" control in the filter bar reveals an inline panel that displays the summary of each review created on this pull request, including the review's author, the review's current state, its summary comment, and a progress bar showing how many of the review comments associated with this review have been marked as resolved. -> TODO: Illustrate the "review summary" list panel +![review summary list panel](https://user-images.githubusercontent.com/17565/50930369-e172ed00-142d-11e9-8ae4-00106dde80f5.png) Clicking the checkbox within each review summary block hides or reveals the review summary comments associated with that review in diff on this tab. Clicking the "Collapse review summaries" control conceals the review summary panel again. From 3aeb59e0ca3feb8dce1b32e8f78911dd9a7469d8 Mon Sep 17 00:00:00 2001 From: Ash Wilson Date: Wed, 9 Jan 2019 17:01:29 -0500 Subject: [PATCH 05/20] What I'm picturing for the PullRequestReviewsItem --- docs/feature-requests/003-pull-request-review.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/feature-requests/003-pull-request-review.md b/docs/feature-requests/003-pull-request-review.md index 2eaf6dd336..2fc225648d 100644 --- a/docs/feature-requests/003-pull-request-review.md +++ b/docs/feature-requests/003-pull-request-review.md @@ -130,7 +130,7 @@ This item is opened in the workspace's right dock when the user: It shows a scrollable view of all of the reviews and comments associated with a specific pull request, -> TODO: Illustration for the PullRequestReviewsItem +![pull request reviews item](https://user-images.githubusercontent.com/17565/50931285-213ad400-1430-11e9-8dd2-bd0cc98216fa.png) Reviews are sorted by "urgency," showing reviews that still need to be addressed at the top. Within each group, sorting is done by "newest first". From 49d12128b36ddf3bd0ea36be9db7bc2f8efe5cf1 Mon Sep 17 00:00:00 2001 From: simurai Date: Thu, 17 Jan 2019 17:21:59 +0900 Subject: [PATCH 06/20] Replace PR list with progress bars --- docs/feature-requests/003-pull-request-review.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/feature-requests/003-pull-request-review.md b/docs/feature-requests/003-pull-request-review.md index 2fc225648d..4d30fdd02b 100644 --- a/docs/feature-requests/003-pull-request-review.md +++ b/docs/feature-requests/003-pull-request-review.md @@ -18,7 +18,7 @@ Peer review is also a critical part of the path to acceptance for pull requests ### Pull Request list -![image](https://user-images.githubusercontent.com/378023/46524357-89bf6580-c8c3-11e8-8e2d-ea02d5a1f278.png) +![image](https://user-images.githubusercontent.com/378023/51304737-4658c380-1a7c-11e9-8edb-7ceafeedabe5.png) * Review progress is indicated for open pull requests listed in the GitHub panel. * The pull request corresponding to the checked out branch gets special treatment in its own section at the top of the list. From 6c6a5b6050856bd0df91e329f3efda3e3801c1aa Mon Sep 17 00:00:00 2001 From: simurai Date: Thu, 17 Jan 2019 17:31:08 +0900 Subject: [PATCH 07/20] Replace PR list actions --- docs/feature-requests/003-pull-request-review.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/feature-requests/003-pull-request-review.md b/docs/feature-requests/003-pull-request-review.md index 4d30fdd02b..6cc1655e77 100644 --- a/docs/feature-requests/003-pull-request-review.md +++ b/docs/feature-requests/003-pull-request-review.md @@ -23,10 +23,10 @@ Peer review is also a critical part of the path to acceptance for pull requests * Review progress is indicated for open pull requests listed in the GitHub panel. * The pull request corresponding to the checked out branch gets special treatment in its own section at the top of the list. -![center pane](https://user-images.githubusercontent.com/378023/46985265-75c9fe00-d124-11e8-9b34-572cd1aaf701.png) +![center pane](https://user-images.githubusercontent.com/378023/51305096-45746180-1a7d-11e9-801b-37b3ab0c862a.png) * Clicking a pull request in the list opens a `PullRequestDetailItem` in the workspace center. -* Clicking the "Reviews" label or progress bar opens a `PullRequestReviewsItem` in the right dock. +* Clicking the progress bar opens a `PullRequestReviewsItem` in the left dock. ### PullRequestDetailItem From b72a00655442b3026d78d8e77bf4299849df2e10 Mon Sep 17 00:00:00 2001 From: simurai Date: Thu, 17 Jan 2019 17:35:29 +0900 Subject: [PATCH 08/20] Replace header and footer Plus remove outdated mockups --- docs/feature-requests/003-pull-request-review.md | 12 +++--------- 1 file changed, 3 insertions(+), 9 deletions(-) diff --git a/docs/feature-requests/003-pull-request-review.md b/docs/feature-requests/003-pull-request-review.md index 6cc1655e77..a99d9e2a4a 100644 --- a/docs/feature-requests/003-pull-request-review.md +++ b/docs/feature-requests/003-pull-request-review.md @@ -32,7 +32,7 @@ Peer review is also a critical part of the path to acceptance for pull requests #### Header -![header](https://user-images.githubusercontent.com/378023/46536358-3829d180-c8e9-11e8-9167-3d1003ab566b.png) +![header](https://user-images.githubusercontent.com/378023/51305325-e400c280-1a7d-11e9-9b4e-b9cf2d326dd5.png) At the top of each `PullRequestDetailItem` is a summary about the pull request, followed by the tabs to switch between different sub-views. @@ -45,15 +45,9 @@ Below the tabs is a "tools bar" with controls to toggle review comments or colla #### Footer -> TODO: Add "open" button +![reviews panel](https://user-images.githubusercontent.com/378023/51305353-f2e77500-1a7d-11e9-96f0-da879d49da3a.png) -![reviews panel](https://user-images.githubusercontent.com/378023/46536010-17ad4780-c8e8-11e8-8338-338bb592efc5.png) - -A panel at the bottom of the pane shows the progress for resolved review comments. It also has a "Review Changes" button to create a new review. This panel is persistent throughout all sub-views. It allows creating new reviews no matter where you are. Below examples with the existing sub-views: - -Overview | Commits | Build Status ---- | --- | --- -![overview](https://user-images.githubusercontent.com/378023/46535907-ca30da80-c8e7-11e8-9401-2b8660d56c25.png) | ![commits](https://user-images.githubusercontent.com/378023/46535908-ca30da80-c8e7-11e8-87ca-01637f2554b6.png) | ![build status](https://user-images.githubusercontent.com/378023/46535909-cac97100-c8e7-11e8-8813-47fdaa3ece57.png) +A panel at the bottom of the pane shows the progress for resolved review comments. It also has a "Review Changes" button to create a new review. This panel is persistent throughout all sub-views. It allows creating new reviews no matter where you are. When the pull request is checked out, an "open" button is shown in the review footer. Clicking "open" opens a `PullRequestReviewsItem` for this pull request's review comments as an item in the right workspace dock. From 5ca37fb4196e0489d6137fed740099823badac97 Mon Sep 17 00:00:00 2001 From: simurai Date: Thu, 17 Jan 2019 17:54:33 +0900 Subject: [PATCH 09/20] Update "Files" mockups --- docs/feature-requests/003-pull-request-review.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/feature-requests/003-pull-request-review.md b/docs/feature-requests/003-pull-request-review.md index a99d9e2a4a..2b22be338d 100644 --- a/docs/feature-requests/003-pull-request-review.md +++ b/docs/feature-requests/003-pull-request-review.md @@ -55,15 +55,15 @@ When the pull request is checked out, an "open" button is shown in the review fo Clicking on the "Files Changed" tab displays the full, multi-file diff associated with the pull request. This is akin to the "Files changed" tab on dotcom. -> TODO: Change "Show review comments" checkbox to an expand/collapse review summaries control - -![files](https://user-images.githubusercontent.com/378023/46536560-d3bb4200-c8e9-11e8-9764-dca0b84245cf.png) +![files](https://user-images.githubusercontent.com/378023/51305826-43ab9d80-1a7f-11e9-8b41-42bc4812d214.png) Clicking on the "Expand review summaries" control in the filter bar reveals an inline panel that displays the summary of each review created on this pull request, including the review's author, the review's current state, its summary comment, and a progress bar showing how many of the review comments associated with this review have been marked as resolved. -![review summary list panel](https://user-images.githubusercontent.com/17565/50930369-e172ed00-142d-11e9-8ae4-00106dde80f5.png) +![review summary list panel](https://user-images.githubusercontent.com/378023/51305827-43ab9d80-1a7f-11e9-90be-902e541b805f.png) + +Clicking on "Comments" within each review summary block hides or reveals the review summary comments associated with that review in diff on this tab. Clicking the "Collapse review summaries" control conceals the review summary panel again. -Clicking the checkbox within each review summary block hides or reveals the review summary comments associated with that review in diff on this tab. Clicking the "Collapse review summaries" control conceals the review summary panel again. +![review summary list panel with comments](https://user-images.githubusercontent.com/378023/51306485-ca14af00-1a80-11e9-8e52-bb4d55928736.png) Beneath the review summary panel is the pull request's combined diff. Diffs are editable, but _only_ if the pull request branch is checked out and the local branch history has not diverged incompatibly from the remote branch history. From dccb70a740d932fa658524d885c238839e8be907 Mon Sep 17 00:00:00 2001 From: simurai Date: Thu, 17 Jan 2019 17:58:30 +0900 Subject: [PATCH 10/20] Replace pull request reviews item --- docs/feature-requests/003-pull-request-review.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/feature-requests/003-pull-request-review.md b/docs/feature-requests/003-pull-request-review.md index 2b22be338d..eb03b8e8e2 100644 --- a/docs/feature-requests/003-pull-request-review.md +++ b/docs/feature-requests/003-pull-request-review.md @@ -124,7 +124,7 @@ This item is opened in the workspace's right dock when the user: It shows a scrollable view of all of the reviews and comments associated with a specific pull request, -![pull request reviews item](https://user-images.githubusercontent.com/17565/50931285-213ad400-1430-11e9-8dd2-bd0cc98216fa.png) +![pull request reviews item](https://user-images.githubusercontent.com/378023/51306720-6939a680-1a81-11e9-8eaa-ffd480e3d47f.png) Reviews are sorted by "urgency," showing reviews that still need to be addressed at the top. Within each group, sorting is done by "newest first". From 7290720ff5c37440c1276a7fae6b2283d77ef585 Mon Sep 17 00:00:00 2001 From: simurai Date: Fri, 18 Jan 2019 10:48:16 +0900 Subject: [PATCH 11/20] Add inline diff mockup --- docs/feature-requests/003-pull-request-review.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/feature-requests/003-pull-request-review.md b/docs/feature-requests/003-pull-request-review.md index eb03b8e8e2..3802a51dbb 100644 --- a/docs/feature-requests/003-pull-request-review.md +++ b/docs/feature-requests/003-pull-request-review.md @@ -142,7 +142,7 @@ Clicking on a review comment opens a `TextEditor` on the corresponding position If an open `TextEditor` corresponds to a file that has one or more review comments in an open `PullRequestReviewsItem`, gutter and line decorations are added to the lines that match those review comment positions. The "current" one is styled differently to stand out. -> TODO: Illustrate the "review comment here" gutter and line decorations +![inline diff](https://user-images.githubusercontent.com/378023/51360052-68e6ed00-1b0d-11e9-852e-a51cff4d479e.png) Clicking on the gutter icon reveals the `PullRequestReviewsItem` and highlights that review comment as the "current" one, scrolling to it and expanding its review if necessary. From 8db614da856158790e0d0802d8bbed5237f571c0 Mon Sep 17 00:00:00 2001 From: annthurium Date: Thu, 28 Feb 2019 16:52:22 -0800 Subject: [PATCH 12/20] add details of third iteration --- docs/feature-requests/003-pull-request-review.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/feature-requests/003-pull-request-review.md b/docs/feature-requests/003-pull-request-review.md index 3802a51dbb..d04793a091 100644 --- a/docs/feature-requests/003-pull-request-review.md +++ b/docs/feature-requests/003-pull-request-review.md @@ -119,7 +119,7 @@ Clicking "Finish your review" from a comment or clicking "Review Changes" in the This item is opened in the workspace's right dock when the user: * Clicks the review progress bar in the GitHub tab. -* Clicks the "open" button on the review summary footer of a `PullRequestDetailItem`. +* Clicks the "open reviews" button on the review summary footer of a `PullRequestDetailItem`. * Clicks the "<>" button on a review comment in the "Files Changed" tab of a `PullRequestDetailItem`. It shows a scrollable view of all of the reviews and comments associated with a specific pull request, @@ -201,6 +201,12 @@ It was a great improvement, but filtering the diff with radio buttons and checkb - Keep using an editable editor for the diffs, but add some padding. - Introduce a "Reviews" footer to all sub-views to allow creating/submit a review, no matter where you are. +#### Third iteration + +Long comments can disrupt the code editing experience. Our third iteration keeps the review comments in a dock, a la Google Docs. This helps code authors more easily address comments, because they can see the comments and also get them out of the way. + +Since this approach different from previous approaches, we performed a series of [usability studies](https://github.com/github/pe-editor-tools/blob/master/community/usability-testing/atom_rcid_research_summary.md) to validate that users would find this approach useful. + ## Unresolved questions From 37b09dc9da4c99aae316c41c17058de328f58009 Mon Sep 17 00:00:00 2001 From: annthurium Date: Thu, 28 Feb 2019 17:00:04 -0800 Subject: [PATCH 13/20] remove section about review summary tab since we're not implementing that. --- docs/feature-requests/003-pull-request-review.md | 9 +-------- 1 file changed, 1 insertion(+), 8 deletions(-) diff --git a/docs/feature-requests/003-pull-request-review.md b/docs/feature-requests/003-pull-request-review.md index d04793a091..70d461456c 100644 --- a/docs/feature-requests/003-pull-request-review.md +++ b/docs/feature-requests/003-pull-request-review.md @@ -57,15 +57,8 @@ Clicking on the "Files Changed" tab displays the full, multi-file diff associate ![files](https://user-images.githubusercontent.com/378023/51305826-43ab9d80-1a7f-11e9-8b41-42bc4812d214.png) -Clicking on the "Expand review summaries" control in the filter bar reveals an inline panel that displays the summary of each review created on this pull request, including the review's author, the review's current state, its summary comment, and a progress bar showing how many of the review comments associated with this review have been marked as resolved. -![review summary list panel](https://user-images.githubusercontent.com/378023/51305827-43ab9d80-1a7f-11e9-90be-902e541b805f.png) - -Clicking on "Comments" within each review summary block hides or reveals the review summary comments associated with that review in diff on this tab. Clicking the "Collapse review summaries" control conceals the review summary panel again. - -![review summary list panel with comments](https://user-images.githubusercontent.com/378023/51306485-ca14af00-1a80-11e9-8e52-bb4d55928736.png) - -Beneath the review summary panel is the pull request's combined diff. Diffs are editable, but _only_ if the pull request branch is checked out and the local branch history has not diverged incompatibly from the remote branch history. +Diffs are editable, but _only_ if the pull request branch is checked out and the local branch history has not diverged incompatibly from the remote branch history. For large diffs, the files can be collapsed to get a better overview. From 145d276b4d52256714794abd719344a0690cd758 Mon Sep 17 00:00:00 2001 From: annthurium Date: Thu, 28 Feb 2019 17:01:47 -0800 Subject: [PATCH 14/20] "resolved conversation" buttons are now "mark as resolved" buttons. --- docs/feature-requests/003-pull-request-review.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/feature-requests/003-pull-request-review.md b/docs/feature-requests/003-pull-request-review.md index 70d461456c..095e6ae724 100644 --- a/docs/feature-requests/003-pull-request-review.md +++ b/docs/feature-requests/003-pull-request-review.md @@ -104,7 +104,7 @@ Clicking "Finish your review" from a comment or clicking "Review Changes" in the ![resolve a review](https://user-images.githubusercontent.com/378023/46927875-c08b3d80-d072-11e8-978b-024111312d79.png) -* Review comments can be resolved by clicking on the "Resolve conversation" buttons. +* Review comments can be resolved by clicking on the "Mark as resolved" buttons. * If the "reply..." editor has non-whitespace content, it is submitted as a final comment first. ### PullRequestReviewsItem From bbb5f2cdcc6684d724bce85fdab83c940bd2ed0a Mon Sep 17 00:00:00 2001 From: annthurium Date: Thu, 28 Feb 2019 17:46:33 -0800 Subject: [PATCH 15/20] the tab is current "files" not "files changed" --- docs/feature-requests/003-pull-request-review.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/feature-requests/003-pull-request-review.md b/docs/feature-requests/003-pull-request-review.md index 095e6ae724..240a1bfc9d 100644 --- a/docs/feature-requests/003-pull-request-review.md +++ b/docs/feature-requests/003-pull-request-review.md @@ -51,7 +51,7 @@ A panel at the bottom of the pane shows the progress for resolved review comment When the pull request is checked out, an "open" button is shown in the review footer. Clicking "open" opens a `PullRequestReviewsItem` for this pull request's review comments as an item in the right workspace dock. -### Files Changed (tab) +### Files (tab) Clicking on the "Files Changed" tab displays the full, multi-file diff associated with the pull request. This is akin to the "Files changed" tab on dotcom. From bf18eb71672ee3b9c13813929bd5ce00bf8d8c34 Mon Sep 17 00:00:00 2001 From: annthurium Date: Thu, 28 Feb 2019 17:48:53 -0800 Subject: [PATCH 16/20] add clarifying point about migrating PullRequestDetailView to dock --- docs/feature-requests/003-pull-request-review.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/feature-requests/003-pull-request-review.md b/docs/feature-requests/003-pull-request-review.md index 240a1bfc9d..7c2625d593 100644 --- a/docs/feature-requests/003-pull-request-review.md +++ b/docs/feature-requests/003-pull-request-review.md @@ -200,6 +200,8 @@ Long comments can disrupt the code editing experience. Our third iteration keep Since this approach different from previous approaches, we performed a series of [usability studies](https://github.com/github/pe-editor-tools/blob/master/community/usability-testing/atom_rcid_research_summary.md) to validate that users would find this approach useful. +We may at some point want to migrate the entire PullRequestDetailView from the pane item to the dock, so as not to duplicate information. However, in the interest of getting code review in the editor shipped, we'll keep the pane item around in the short term. + ## Unresolved questions From 3c4580d1f19eae2c6b8fbfa514c4077e1fd68e79 Mon Sep 17 00:00:00 2001 From: Tilde Ann Thurium Date: Thu, 28 Feb 2019 17:55:06 -0800 Subject: [PATCH 17/20] add new screenshot of PullRequestReviewsItem --- docs/feature-requests/003-pull-request-review.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/feature-requests/003-pull-request-review.md b/docs/feature-requests/003-pull-request-review.md index 7c2625d593..36ba29914f 100644 --- a/docs/feature-requests/003-pull-request-review.md +++ b/docs/feature-requests/003-pull-request-review.md @@ -117,7 +117,7 @@ This item is opened in the workspace's right dock when the user: It shows a scrollable view of all of the reviews and comments associated with a specific pull request, -![pull request reviews item](https://user-images.githubusercontent.com/378023/51306720-6939a680-1a81-11e9-8eaa-ffd480e3d47f.png) +![pull request reviews item](https://user-images.githubusercontent.com/3781742/53610984-c85f0080-3b81-11e9-9a82-9df43b6410f3.png) Reviews are sorted by "urgency," showing reviews that still need to be addressed at the top. Within each group, sorting is done by "newest first". From 4718550ccef8d64f5a128ebc60b9b98f48aa7a1f Mon Sep 17 00:00:00 2001 From: Tilde Ann Thurium Date: Thu, 28 Feb 2019 18:08:59 -0800 Subject: [PATCH 18/20] add screenshot of expanded RCID comment --- docs/feature-requests/003-pull-request-review.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/docs/feature-requests/003-pull-request-review.md b/docs/feature-requests/003-pull-request-review.md index 36ba29914f..9af4f95f1e 100644 --- a/docs/feature-requests/003-pull-request-review.md +++ b/docs/feature-requests/003-pull-request-review.md @@ -129,7 +129,14 @@ Reviews are sorted by "urgency," showing reviews that still need to be addressed Clicking on a review summary comment expands or collapses the associated review comments. -Clicking on a review comment opens a `TextEditor` on the corresponding position of the file under review. The clicked review comment is highlighted as the "current" one. +screen shot 2019-02-28 at 6 03 50 pm + +In addition to the comment, users see an abbreviated version of the diff, with 4 context lines. + +Clicking on the "Jump To File" button opens a `TextEditor` on the corresponding position of the file under review. The clicked review comment is highlighted as the "current" one. + +Clicking on the "View Changes" button opens the "Files" tab of the `PullRequestDetailsView`, so the user can see the full diff. + #### Within an open TextEditor From 6dd375269107368d17e05bf950827d6761937b96 Mon Sep 17 00:00:00 2001 From: Tilde Ann Thurium Date: Thu, 28 Feb 2019 18:13:45 -0800 Subject: [PATCH 19/20] update footer screenshot --- docs/feature-requests/003-pull-request-review.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/feature-requests/003-pull-request-review.md b/docs/feature-requests/003-pull-request-review.md index 9af4f95f1e..a4823c9aad 100644 --- a/docs/feature-requests/003-pull-request-review.md +++ b/docs/feature-requests/003-pull-request-review.md @@ -45,7 +45,7 @@ Below the tabs is a "tools bar" with controls to toggle review comments or colla #### Footer -![reviews panel](https://user-images.githubusercontent.com/378023/51305353-f2e77500-1a7d-11e9-96f0-da879d49da3a.png) +![reviews panel](https://user-images.githubusercontent.com/3781742/53611708-5805ae80-3b84-11e9-915d-fb29476e3001.png) A panel at the bottom of the pane shows the progress for resolved review comments. It also has a "Review Changes" button to create a new review. This panel is persistent throughout all sub-views. It allows creating new reviews no matter where you are. From 51e2f848b86a75341b9f3f4da57be990f7506b5e Mon Sep 17 00:00:00 2001 From: Tilde Ann Thurium Date: Thu, 28 Feb 2019 18:16:36 -0800 Subject: [PATCH 20/20] clarify button copy --- docs/feature-requests/003-pull-request-review.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/feature-requests/003-pull-request-review.md b/docs/feature-requests/003-pull-request-review.md index a4823c9aad..920072e4bd 100644 --- a/docs/feature-requests/003-pull-request-review.md +++ b/docs/feature-requests/003-pull-request-review.md @@ -49,7 +49,7 @@ Below the tabs is a "tools bar" with controls to toggle review comments or colla A panel at the bottom of the pane shows the progress for resolved review comments. It also has a "Review Changes" button to create a new review. This panel is persistent throughout all sub-views. It allows creating new reviews no matter where you are. -When the pull request is checked out, an "open" button is shown in the review footer. Clicking "open" opens a `PullRequestReviewsItem` for this pull request's review comments as an item in the right workspace dock. +When the pull request is checked out, an "Open Reviews" button is shown in the review footer. Clicking "Open Reviews" opens a `PullRequestReviewsItem` for this pull request's review comments as an item in the right workspace dock. ### Files (tab)