From 781f0887fa57f74febb32f2ac48690167900f7da Mon Sep 17 00:00:00 2001 From: Vanessa Yuen Date: Fri, 19 Apr 2019 00:16:12 -0400 Subject: [PATCH 01/19] get started with a new RFC for the reviewer flow --- .../006-pull-request-reviewer-flow.md | 61 +++++++++++++++++++ 1 file changed, 61 insertions(+) create mode 100644 docs/feature-requests/006-pull-request-reviewer-flow.md diff --git a/docs/feature-requests/006-pull-request-reviewer-flow.md b/docs/feature-requests/006-pull-request-reviewer-flow.md new file mode 100644 index 0000000000..c126d4ef79 --- /dev/null +++ b/docs/feature-requests/006-pull-request-reviewer-flow.md @@ -0,0 +1,61 @@ + + +**_Part 1 - Required information_** + +# Pull Request Review -- Reviewer Flow + +## :memo: Summary + +Provide code review to an existing pull request within Atom. + +*Note*: This RFC is an iteration of the [original RFC for Pull Request Review](./003-pull-request-review.md). + +## :checkered_flag: Motivation + +We already have a workflow built out for the receiving end of pull request reviews; it only makes sense to also build out a workflow for users to author pull request reviews. + +## 🤯 Explanation + + + +Explain the proposal as if it was already implemented in the GitHub package and you were describing it to an Atom user. That generally means: + +- Introducing new named concepts. +- Explaining the feature largely in terms of examples. +- Explaining any changes to existing workflows. +- Design mock-ups or diagrams depicting any new UI that will be introduced. + + +**_Part 2 - Additional information_** + +## :anchor: Drawbacks + +Why should we *not* do this? + +## :thinking: Rationale and alternatives + +- Why is this approach the best in the space of possible approaches? +- What other approaches have been considered and what is the rationale for not choosing them? +- What is the impact of not doing this? + +## :question: Unresolved questions + +- What unresolved questions do you expect to resolve through the Feature Request process before this gets merged? +- What unresolved questions do you expect to resolve through the implementation of this feature before it is released in a new version of the package? + +## :warning: Out of Scope + +- What related issues do you consider out of scope for this Feature Request that could be addressed in the future independently of the solution that comes out of this Feature Request? + +## :construction: Implementation phases + +- Can this functionality be introduced in multiple, distinct, self-contained pull requests? +- A specification for when the feature is considered "done." + +## :white_check_mark: Feature description for Atom release blog post + +- When this feature is shipped, what would we like to say or show in our Atom release blog post (example: http://blog.atom.io/2018/07/31/atom-1-29.html) +- Feel free to drop ideas and gifs here during development +- Once development is complete, write a blurb for the release coordinator to copy/paste into the Atom release blog From a9ee9404daffeb1218d0d464ea89e3ca78307d0d Mon Sep 17 00:00:00 2001 From: Vanessa Yuen Date: Fri, 19 Apr 2019 15:27:19 -0400 Subject: [PATCH 02/19] add some draft about the overview of components still thinking about how to structure the explanation --- .../006-pull-request-reviewer-flow.md | 45 ++++++++++++++++--- 1 file changed, 39 insertions(+), 6 deletions(-) diff --git a/docs/feature-requests/006-pull-request-reviewer-flow.md b/docs/feature-requests/006-pull-request-reviewer-flow.md index c126d4ef79..6d5593f534 100644 --- a/docs/feature-requests/006-pull-request-reviewer-flow.md +++ b/docs/feature-requests/006-pull-request-reviewer-flow.md @@ -14,18 +14,51 @@ Provide code review to an existing pull request within Atom. ## :checkered_flag: Motivation -We already have a workflow built out for the receiving end of pull request reviews; it only makes sense to also build out a workflow for users to author pull request reviews. +We already have an innovative review-comments-in-dock (RCID) workflow built out for the receiving end of pull request reviews. In order to complete the full experience of code review within Atom, we should also build out a workflow for users to author pull request reviews. ## 🤯 Explanation +### "All Reviews" tab +This tab shows all review summaries and review comments, including the ones that are part of a _pending review_ that has not been submitted yet. + +#### Header +- When there is no pending review, button reads "Start a pending review", clicking on which will take you to the Pending Review tab in its empty state. +- When there is already a pending review, the button reads "Resume review (2)". The number indicates the number of comments currently in the pending review. When adding more pending comments _within the All Reviews tab_, there should be some emphasis on the number changing -- akin to the button on dotcom. Clicking on this button takes user to the Pending Review tab. + + +- rationale for scaling down the "Checkout" button +- caveats of doing so +- mitigation + +#### Responding to a comment thread +start a new review button + +#### Pending comments + +Pending comments within the All Reviews tab are styled differently from the already published comments. Pending comments contain a way to direct user to the Pending Review tab. + + + + +### "Pending Review" tab +This tab shows a *subset* of all reviews -- only the summary and comments of a pending review. Since a user is only allowed to have one pending review at a time, there should also only be one active Pending Review tab. + +#### Header +The header looks very similar to the one of All Reviews tab, with the exception that the primary button now reads "See all reviews", and will send users back to the All Reviews tab. + + +#### Summary section + +- sticky +- drop down to select review type +- button to submit review + +#### Comments section + +- empty state -Explain the proposal as if it was already implemented in the GitHub package and you were describing it to an Atom user. That generally means: -- Introducing new named concepts. -- Explaining the feature largely in terms of examples. -- Explaining any changes to existing workflows. -- Design mock-ups or diagrams depicting any new UI that will be introduced. **_Part 2 - Additional information_** From 942238e65aa4e2df81b6d217d1ff949e9d266675 Mon Sep 17 00:00:00 2001 From: Vanessa Yuen Date: Fri, 19 Apr 2019 15:51:20 -0400 Subject: [PATCH 03/19] add some outline for the workflow explanation --- .../006-pull-request-reviewer-flow.md | 34 ++++++++++++++++--- 1 file changed, 30 insertions(+), 4 deletions(-) diff --git a/docs/feature-requests/006-pull-request-reviewer-flow.md b/docs/feature-requests/006-pull-request-reviewer-flow.md index 6d5593f534..6cedea3626 100644 --- a/docs/feature-requests/006-pull-request-reviewer-flow.md +++ b/docs/feature-requests/006-pull-request-reviewer-flow.md @@ -1,7 +1,3 @@ - - **_Part 1 - Required information_** # Pull Request Review -- Reviewer Flow @@ -60,6 +56,36 @@ The header looks very similar to the one of All Reviews tab, with the exception +### Reviewer Workflow + +**Note**: In the name of clarity, in this RFC we will differentiate between "new comment" and "pending comment": +- a new comment: _after_ a user decides to add a comment from the gutter, and _before_ the user actually adds it to a pending review. (i.e. a pending-pending comment, if you prefer confusion. :laughing:) +- a pending comment: already added to a pending review + +#### 1. Start a review + +##### From the gutter + +within Files tab in `PullRequestDetailView` +within an editor + +If user has checked out a PR branch, an "add comment" icon should show up *on hover* over the gutter of an editor of any file. Clicking on the icon will either activate new comment + +Nothing if not on a PR branch. + +##### By responding to a thread + +#### 2. Continue a review + + + +#### 3. Submit a review +- The only way to submit a review within Atom is by using the "Submit review" button in the Pending Review tab +- the button will be disabled if a review type has not been chosen from the dropdown menu +- if there is any new comment that has not been added to the pending review, a warning modal should pop up +- after publishing, the Pending Review tab will be destroyed. User will be led back to the All Reviews tab, which will immediately reflect the just published review. + +-------------------- **_Part 2 - Additional information_** From da7023e2f1fb3eae85192fad5337dc24b8dbcf01 Mon Sep 17 00:00:00 2001 From: Vanessa Yuen Date: Fri, 19 Apr 2019 18:32:55 -0400 Subject: [PATCH 04/19] grammar --- .../006-pull-request-reviewer-flow.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/feature-requests/006-pull-request-reviewer-flow.md b/docs/feature-requests/006-pull-request-reviewer-flow.md index 6cedea3626..ff249843fc 100644 --- a/docs/feature-requests/006-pull-request-reviewer-flow.md +++ b/docs/feature-requests/006-pull-request-reviewer-flow.md @@ -10,7 +10,7 @@ Provide code review to an existing pull request within Atom. ## :checkered_flag: Motivation -We already have an innovative review-comments-in-dock (RCID) workflow built out for the receiving end of pull request reviews. In order to complete the full experience of code review within Atom, we should also build out a workflow for users to author pull request reviews. +We already have an innovative review-comments-in-dock (RCID) workflow built out for the receiving end of pull request reviews. In order to complete the full code review experience within Atom, we should also build out a workflow for users to author pull request reviews. ## 🤯 Explanation @@ -21,9 +21,9 @@ This tab shows all review summaries and review comments, including the ones that - When there is no pending review, button reads "Start a pending review", clicking on which will take you to the Pending Review tab in its empty state. - When there is already a pending review, the button reads "Resume review (2)". The number indicates the number of comments currently in the pending review. When adding more pending comments _within the All Reviews tab_, there should be some emphasis on the number changing -- akin to the button on dotcom. Clicking on this button takes user to the Pending Review tab. - -- rationale for scaling down the "Checkout" button -- caveats of doing so +##### On scaling down the "Checkout" button to just an icon +- rationale +- caveats - mitigation #### Responding to a comment thread @@ -80,10 +80,10 @@ Nothing if not on a PR branch. #### 3. Submit a review -- The only way to submit a review within Atom is by using the "Submit review" button in the Pending Review tab -- the button will be disabled if a review type has not been chosen from the dropdown menu -- if there is any new comment that has not been added to the pending review, a warning modal should pop up -- after publishing, the Pending Review tab will be destroyed. User will be led back to the All Reviews tab, which will immediately reflect the just published review. +- The only way to submit a review within Atom is by using the "Submit review" button in the Pending Review tab. +- The button will be disabled if a review type has not been chosen from the dropdown menu. +- If there is any new comment that has not been added to the pending review, a warning modal should pop up. +- After publishing, the Pending Review tab will be destroyed. User will be led back to the All Reviews tab, which will immediately reflect the just published review. -------------------- From 6682d2e54ecabc56fa8414aa66af55b7b939a70b Mon Sep 17 00:00:00 2001 From: Vanessa Yuen Date: Fri, 19 Apr 2019 18:55:29 -0400 Subject: [PATCH 05/19] add header screenshot --- docs/feature-requests/006-pull-request-reviewer-flow.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/feature-requests/006-pull-request-reviewer-flow.md b/docs/feature-requests/006-pull-request-reviewer-flow.md index ff249843fc..253a21a3eb 100644 --- a/docs/feature-requests/006-pull-request-reviewer-flow.md +++ b/docs/feature-requests/006-pull-request-reviewer-flow.md @@ -18,7 +18,11 @@ We already have an innovative review-comments-in-dock (RCID) workflow built out This tab shows all review summaries and review comments, including the ones that are part of a _pending review_ that has not been submitted yet. #### Header -- When there is no pending review, button reads "Start a pending review", clicking on which will take you to the Pending Review tab in its empty state. +| current header | proposed header | proposed header with pending review | +|---|---| --- | +|old header|new header|new header| + +- When there is no pending review, button reads "Start a review", clicking on which will take you to the Pending Review tab in its empty state. - When there is already a pending review, the button reads "Resume review (2)". The number indicates the number of comments currently in the pending review. When adding more pending comments _within the All Reviews tab_, there should be some emphasis on the number changing -- akin to the button on dotcom. Clicking on this button takes user to the Pending Review tab. ##### On scaling down the "Checkout" button to just an icon From 52e9782b8407da215213d51e0dc6a29089740f84 Mon Sep 17 00:00:00 2001 From: Vanessa Yuen Date: Wed, 24 Apr 2019 17:57:28 -0400 Subject: [PATCH 06/19] add an alternative to header :thinking: --- docs/feature-requests/006-pull-request-reviewer-flow.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/docs/feature-requests/006-pull-request-reviewer-flow.md b/docs/feature-requests/006-pull-request-reviewer-flow.md index 253a21a3eb..5f89b19501 100644 --- a/docs/feature-requests/006-pull-request-reviewer-flow.md +++ b/docs/feature-requests/006-pull-request-reviewer-flow.md @@ -23,12 +23,10 @@ This tab shows all review summaries and review comments, including the ones that |old header|new header|new header| - When there is no pending review, button reads "Start a review", clicking on which will take you to the Pending Review tab in its empty state. -- When there is already a pending review, the button reads "Resume review (2)". The number indicates the number of comments currently in the pending review. When adding more pending comments _within the All Reviews tab_, there should be some emphasis on the number changing -- akin to the button on dotcom. Clicking on this button takes user to the Pending Review tab. +- When there is already a pending review, the button reads "Resume review (2)". The number is a counter of comments currently in the pending review. When adding more pending comments _within the All Reviews tab_ (more on that flow below), there should be some emphasis on the counter changing -- akin to the button on dotcom. Clicking on this button takes user to the Pending Review tab. -##### On scaling down the "Checkout" button to just an icon -- rationale -- caveats -- mitigation +##### Alternative: footer +An alternative would be to add a footer bar at the bottom and place the add review button there. The caveat is that it might not be as noticeable as the header, and "start a new review" is an arguably more important action than "checkout". #### Responding to a comment thread start a new review button From 83f7ced2cc313a9b34eb14c4f87326201c2724b3 Mon Sep 17 00:00:00 2001 From: Vanessa Yuen Date: Wed, 24 Apr 2019 17:58:03 -0400 Subject: [PATCH 07/19] Add some screenshots --- .../006-pull-request-reviewer-flow.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/docs/feature-requests/006-pull-request-reviewer-flow.md b/docs/feature-requests/006-pull-request-reviewer-flow.md index 5f89b19501..fa75b97c65 100644 --- a/docs/feature-requests/006-pull-request-reviewer-flow.md +++ b/docs/feature-requests/006-pull-request-reviewer-flow.md @@ -29,17 +29,21 @@ This tab shows all review summaries and review comments, including the ones that An alternative would be to add a footer bar at the bottom and place the add review button there. The caveat is that it might not be as noticeable as the header, and "start a new review" is an arguably more important action than "checkout". #### Responding to a comment thread -start a new review button +![responding to a comment thread](https://user-images.githubusercontent.com/6842965/56689748-cdd05700-66a9-11e9-90e8-266c69cbc589.png) -#### Pending comments +User can respond to a comment thread by adding a single line comment (current implementation) or starting a new review. The two buttons should only show up when the comment textbox is in focus, or is _not_ empty. + +When there is already an existing pending review, there should only be **one** `btn-primary` button that reads "Comment". -Pending comments within the All Reviews tab are styled differently from the already published comments. Pending comments contain a way to direct user to the Pending Review tab. +#### Pending comments +![image](https://user-images.githubusercontent.com/6842965/56692893-2ce59a00-66b1-11e9-81cc-bc7956bc8bec.png) +Pending comments within the All Reviews tab are styled differently from the already published comments. Pending comments contain a badge, and when clicked, it will take user to the Pending Review tab. ### "Pending Review" tab -This tab shows a *subset* of all reviews -- only the summary and comments of a pending review. Since a user is only allowed to have one pending review at a time, there should also only be one active Pending Review tab. +This tab shows *a subset* of all reviews -- only the summary and comments of a pending review. Since a user is only allowed to have one pending review at a time, there should also only be maximum one Pending Review tab. #### Header The header looks very similar to the one of All Reviews tab, with the exception that the primary button now reads "See all reviews", and will send users back to the All Reviews tab. From e309b2fdd79caff4b84dd1922d30b467600b77bb Mon Sep 17 00:00:00 2001 From: Vanessa Yuen Date: Wed, 24 Apr 2019 17:58:18 -0400 Subject: [PATCH 08/19] New comment screenshot --- docs/feature-requests/006-pull-request-reviewer-flow.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/feature-requests/006-pull-request-reviewer-flow.md b/docs/feature-requests/006-pull-request-reviewer-flow.md index fa75b97c65..84f04d0244 100644 --- a/docs/feature-requests/006-pull-request-reviewer-flow.md +++ b/docs/feature-requests/006-pull-request-reviewer-flow.md @@ -60,6 +60,9 @@ The header looks very similar to the one of All Reviews tab, with the exception - empty state +### New Comment +![image](https://user-images.githubusercontent.com/6842965/56695406-fdd22700-66b6-11e9-9e7e-fe85e2507a66.png) + ### Reviewer Workflow From b74359b76371830fa7e65cb8ab42b705c62daac7 Mon Sep 17 00:00:00 2001 From: Vanessa Yuen Date: Wed, 24 Apr 2019 17:58:54 -0400 Subject: [PATCH 09/19] add section on "add comment" gutter icon flow --- .../006-pull-request-reviewer-flow.md | 29 +++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/docs/feature-requests/006-pull-request-reviewer-flow.md b/docs/feature-requests/006-pull-request-reviewer-flow.md index 84f04d0244..ae45e6dc62 100644 --- a/docs/feature-requests/006-pull-request-reviewer-flow.md +++ b/docs/feature-requests/006-pull-request-reviewer-flow.md @@ -64,6 +64,35 @@ The header looks very similar to the one of All Reviews tab, with the exception ![image](https://user-images.githubusercontent.com/6842965/56695406-fdd22700-66b6-11e9-9e7e-fe85e2507a66.png) +### "Add comment" gutter icon + +A user can start a review or add a comment to an existing pending review by clicking on the "add comment" icon which shows up on hover over the gutter of: + +1. MultiFilePatch view within Files tab in `PullRequestDetailView` +2. an editor *if on a checked out PR branch* + +The flow of starting a review or adding a comment from the gutter varies a bit depending on the state of reviews: + +* If there is no reviews at all + 1. User clicks on "add comment" icon in gutter + 2. *Pending reiview* dock opens in empty state + 3. New comment block is added to the pending review dock + + +* If there are existing reviews and no pending review + 1. User clicks on "add comment" icon in gutter + 2. *All reviews* dock open + 3. New comment block is added to the all reviews dock + 4. User can choose between "Add a single comment" or "start a review" + 5. a) "add single comment": comment is added to the all reviews dock + b) "start a review": user is redirected to the pending dock with the newly added pending comment there + + +* If there is a pending review + 1. User clicks on "add comment" icon in gutter + 2. *Pending reviews* dock open + 3. New comment block is added to the pending review dock + ### Reviewer Workflow From a3e0e69effbb8c8e50493d556a347add4155d57e Mon Sep 17 00:00:00 2001 From: Vanessa Yuen Date: Wed, 24 Apr 2019 18:04:58 -0400 Subject: [PATCH 10/19] add section on high level workflow --- .../006-pull-request-reviewer-flow.md | 21 ++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/docs/feature-requests/006-pull-request-reviewer-flow.md b/docs/feature-requests/006-pull-request-reviewer-flow.md index ae45e6dc62..8fd66cfcf0 100644 --- a/docs/feature-requests/006-pull-request-reviewer-flow.md +++ b/docs/feature-requests/006-pull-request-reviewer-flow.md @@ -12,7 +12,26 @@ Provide code review to an existing pull request within Atom. We already have an innovative review-comments-in-dock (RCID) workflow built out for the receiving end of pull request reviews. In order to complete the full code review experience within Atom, we should also build out a workflow for users to author pull request reviews. -## 🤯 Explanation +## 🤯 Workflow Explanation + +This is a high level overview of what the workflow of a PR Review author should look like. More on the functionality and behaviour of each component in the next section. + +#### 1. Start a review + +There are three ways to start a review: +1. Click "Start a review" button on the header of review dock, or footer of PR detail item, or on the empty state of review dock +2. Respond to an existing review thread by clicking "Start a review" +3. Click on a "add comment" icon on the gutter + +#### 2. Continue a review + +Once a pending review has been started, user can add more comments to it by: +1. Responding to an existing review thread +2. Clicking "add comment" icon on the gutter + +#### 3. Submit a review +- The only way to submit a review within Atom is by using the "Submit review" button in the Pending Review tab. + ### "All Reviews" tab This tab shows all review summaries and review comments, including the ones that are part of a _pending review_ that has not been submitted yet. From 99cfc642487e6afce8e8d0a90d8fa34243fc6a15 Mon Sep 17 00:00:00 2001 From: Vanessa Yuen Date: Wed, 24 Apr 2019 18:19:48 -0400 Subject: [PATCH 11/19] moved some sections around --- .../006-pull-request-reviewer-flow.md | 59 ++++++------------- 1 file changed, 18 insertions(+), 41 deletions(-) diff --git a/docs/feature-requests/006-pull-request-reviewer-flow.md b/docs/feature-requests/006-pull-request-reviewer-flow.md index 8fd66cfcf0..ff8b1ac6e6 100644 --- a/docs/feature-requests/006-pull-request-reviewer-flow.md +++ b/docs/feature-requests/006-pull-request-reviewer-flow.md @@ -30,7 +30,9 @@ Once a pending review has been started, user can add more comments to it by: 2. Clicking "add comment" icon on the gutter #### 3. Submit a review -- The only way to submit a review within Atom is by using the "Submit review" button in the Pending Review tab. +The only way to submit a review within Atom is by using the "Submit review" button in the Pending Review tab. After publishing the review, the Pending Review tab will be destroyed. User will be led back to the All Reviews tab, which will immediately reflect the just published review. + +## 🤯 Components Explanation ### "All Reviews" tab @@ -56,9 +58,9 @@ When there is already an existing pending review, there should only be **one** ` #### Pending comments -![image](https://user-images.githubusercontent.com/6842965/56692893-2ce59a00-66b1-11e9-81cc-bc7956bc8bec.png) +![pending comment](https://user-images.githubusercontent.com/6842965/56692893-2ce59a00-66b1-11e9-81cc-bc7956bc8bec.png) -Pending comments within the All Reviews tab are styled differently from the already published comments. Pending comments contain a badge, and when clicked, it will take user to the Pending Review tab. +Pending comments within the All Reviews tab are styled differently from the already published comments. Pending comments contain a badge, and when clicked, will take user to the Pending Review tab. ### "Pending Review" tab @@ -73,6 +75,8 @@ The header looks very similar to the one of All Reviews tab, with the exception - sticky - drop down to select review type - button to submit review +- The button will be disabled if a review type has not been chosen from the dropdown menu. + #### Comments section @@ -80,7 +84,9 @@ The header looks very similar to the one of All Reviews tab, with the exception ### New Comment -![image](https://user-images.githubusercontent.com/6842965/56695406-fdd22700-66b6-11e9-9e7e-fe85e2507a66.png) +![new comment](https://user-images.githubusercontent.com/6842965/56695406-fdd22700-66b6-11e9-9e7e-fe85e2507a66.png) + +A new comment block can appear in either All Reviews tab or Pending Reviews tab, depending on the scenarios covered in "Add comment gutter icon" section below. When in focus, a new comment block always has a glowing border to emphasize itself. If there is already a pending review, there should only be one `btn-primary` button that reads "Comment". ### "Add comment" gutter icon @@ -94,53 +100,24 @@ The flow of starting a review or adding a comment from the gutter varies a bit d * If there is no reviews at all 1. User clicks on "add comment" icon in gutter - 2. *Pending reiview* dock opens in empty state - 3. New comment block is added to the pending review dock + 2. *Pending Review* tab opens in empty state + 3. New comment block is added to the Pending Review tab * If there are existing reviews and no pending review 1. User clicks on "add comment" icon in gutter - 2. *All reviews* dock open - 3. New comment block is added to the all reviews dock + 2. *All Reviews* tab open + 3. New comment block is added to the All Reviews tab 4. User can choose between "Add a single comment" or "start a review" - 5. a) "add single comment": comment is added to the all reviews dock - b) "start a review": user is redirected to the pending dock with the newly added pending comment there + 5. a) "add single comment": comment is added to the All Reviews tab + b) "start a review": user is redirected to the pending tab with the newly added pending comment there * If there is a pending review 1. User clicks on "add comment" icon in gutter - 2. *Pending reviews* dock open - 3. New comment block is added to the pending review dock - - -### Reviewer Workflow - -**Note**: In the name of clarity, in this RFC we will differentiate between "new comment" and "pending comment": -- a new comment: _after_ a user decides to add a comment from the gutter, and _before_ the user actually adds it to a pending review. (i.e. a pending-pending comment, if you prefer confusion. :laughing:) -- a pending comment: already added to a pending review - -#### 1. Start a review - -##### From the gutter + 2. *Pending reviews* tab open + 3. New comment block is added to the Pending Review tab -within Files tab in `PullRequestDetailView` -within an editor - -If user has checked out a PR branch, an "add comment" icon should show up *on hover* over the gutter of an editor of any file. Clicking on the icon will either activate new comment - -Nothing if not on a PR branch. - -##### By responding to a thread - -#### 2. Continue a review - - - -#### 3. Submit a review -- The only way to submit a review within Atom is by using the "Submit review" button in the Pending Review tab. -- The button will be disabled if a review type has not been chosen from the dropdown menu. -- If there is any new comment that has not been added to the pending review, a warning modal should pop up. -- After publishing, the Pending Review tab will be destroyed. User will be led back to the All Reviews tab, which will immediately reflect the just published review. -------------------- From 40109d29d91cf981caf731ad86a7863fcf2b5127 Mon Sep 17 00:00:00 2001 From: Vanessa Yuen Date: Wed, 24 Apr 2019 19:12:29 -0400 Subject: [PATCH 12/19] add section about pending review summary --- .../006-pull-request-reviewer-flow.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/docs/feature-requests/006-pull-request-reviewer-flow.md b/docs/feature-requests/006-pull-request-reviewer-flow.md index ff8b1ac6e6..395aa0056a 100644 --- a/docs/feature-requests/006-pull-request-reviewer-flow.md +++ b/docs/feature-requests/006-pull-request-reviewer-flow.md @@ -66,16 +66,15 @@ Pending comments within the All Reviews tab are styled differently from the alre ### "Pending Review" tab This tab shows *a subset* of all reviews -- only the summary and comments of a pending review. Since a user is only allowed to have one pending review at a time, there should also only be maximum one Pending Review tab. -#### Header +#### Header (or the alternate footer) The header looks very similar to the one of All Reviews tab, with the exception that the primary button now reads "See all reviews", and will send users back to the All Reviews tab. #### Summary section -- sticky -- drop down to select review type -- button to submit review -- The button will be disabled if a review type has not been chosen from the dropdown menu. +![pending review summary](https://user-images.githubusercontent.com/6842965/56699584-23196200-66c4-11e9-94a4-193c9d662bb3.png) + +The summary section of the Pending Review tab is sticky, so it stays within view regardless of how long the list of comments below it is. The icon on the left indicates the type of review, which can be selected in the dropdown underneath the text box. The button to submit review will be disabled a review type has not been chosen from the dropdown menu. #### Comments section @@ -86,7 +85,7 @@ The header looks very similar to the one of All Reviews tab, with the exception ### New Comment ![new comment](https://user-images.githubusercontent.com/6842965/56695406-fdd22700-66b6-11e9-9e7e-fe85e2507a66.png) -A new comment block can appear in either All Reviews tab or Pending Reviews tab, depending on the scenarios covered in "Add comment gutter icon" section below. When in focus, a new comment block always has a glowing border to emphasize itself. If there is already a pending review, there should only be one `btn-primary` button that reads "Comment". +A new comment block can appear in either All Reviews tab or Pending Review tab, depending on the scenarios covered in "Add comment gutter icon" section below. When in focus, a new comment block always has a glowing border to emphasize itself. If there is already a pending review, there should only be one `btn-primary` button that reads "Comment". ### "Add comment" gutter icon From 98d67c6f04083492425df54f72557612bfa057ff Mon Sep 17 00:00:00 2001 From: Vanessa Yuen Date: Wed, 24 Apr 2019 19:18:07 -0400 Subject: [PATCH 13/19] add section about pending comments --- docs/feature-requests/006-pull-request-reviewer-flow.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/feature-requests/006-pull-request-reviewer-flow.md b/docs/feature-requests/006-pull-request-reviewer-flow.md index 395aa0056a..5fe512c141 100644 --- a/docs/feature-requests/006-pull-request-reviewer-flow.md +++ b/docs/feature-requests/006-pull-request-reviewer-flow.md @@ -74,12 +74,16 @@ The header looks very similar to the one of All Reviews tab, with the exception ![pending review summary](https://user-images.githubusercontent.com/6842965/56699584-23196200-66c4-11e9-94a4-193c9d662bb3.png) -The summary section of the Pending Review tab is sticky, so it stays within view regardless of how long the list of comments below it is. The icon on the left indicates the type of review, which can be selected in the dropdown underneath the text box. The button to submit review will be disabled a review type has not been chosen from the dropdown menu. +The summary section of the Pending Review tab is sticky (although still collapsible), so it stays within view regardless of how long the list of comments below it is. The icon on the left indicates the type of review, which can be selected in the dropdown underneath the text box. The button to submit review will be disabled a review type has not been chosen from the dropdown menu. #### Comments section -- empty state +![pending review comments](https://user-images.githubusercontent.com/6842965/56699828-31b44900-66c5-11e9-948c-a5c03215e5d8.png) + +The comments section of the Pending Review tab looks very similar to that of the All Reviews tab, except that the progress bar is replaced by a small comment counter on top of the whole section. + +**Empty State** of this section should contain a picture tutorial of how to add a comment via gutter icon. ### New Comment From 4f10bd7a7ecddea72d336776651b0f8d51a4c019 Mon Sep 17 00:00:00 2001 From: Vanessa Yuen Date: Wed, 24 Apr 2019 19:22:35 -0400 Subject: [PATCH 14/19] fix format --- docs/feature-requests/006-pull-request-reviewer-flow.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/feature-requests/006-pull-request-reviewer-flow.md b/docs/feature-requests/006-pull-request-reviewer-flow.md index 5fe512c141..60c3a79bb3 100644 --- a/docs/feature-requests/006-pull-request-reviewer-flow.md +++ b/docs/feature-requests/006-pull-request-reviewer-flow.md @@ -112,8 +112,7 @@ The flow of starting a review or adding a comment from the gutter varies a bit d 2. *All Reviews* tab open 3. New comment block is added to the All Reviews tab 4. User can choose between "Add a single comment" or "start a review" - 5. a) "add single comment": comment is added to the All Reviews tab - b) "start a review": user is redirected to the pending tab with the newly added pending comment there + 5. (a) "add single comment": comment is added to the All Reviews tab; (b) "start a review": user is redirected to the pending tab with the newly added pending comment there * If there is a pending review From 13ecc2f8faf1532bcd0291c6153fed49964ec9fb Mon Sep 17 00:00:00 2001 From: Vanessa Yuen Date: Wed, 24 Apr 2019 19:33:09 -0400 Subject: [PATCH 15/19] in-page links --- .../006-pull-request-reviewer-flow.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/feature-requests/006-pull-request-reviewer-flow.md b/docs/feature-requests/006-pull-request-reviewer-flow.md index 60c3a79bb3..18a744d84d 100644 --- a/docs/feature-requests/006-pull-request-reviewer-flow.md +++ b/docs/feature-requests/006-pull-request-reviewer-flow.md @@ -20,17 +20,17 @@ This is a high level overview of what the workflow of a PR Review author should There are three ways to start a review: 1. Click "Start a review" button on the header of review dock, or footer of PR detail item, or on the empty state of review dock -2. Respond to an existing review thread by clicking "Start a review" -3. Click on a "add comment" icon on the gutter +2. [Respond to an existing review thread by clicking "Start a review"](#responding-to-a-comment-thread) +3. [Click on a "add comment" icon on the gutter](#add-comment-gutter-icon) #### 2. Continue a review Once a pending review has been started, user can add more comments to it by: -1. Responding to an existing review thread -2. Clicking "add comment" icon on the gutter +1. [Responding to an existing review thread](#responding-to-a-comment-thread) +2. [Clicking "add comment" icon on the gutter](#add-comment-gutter-icon) #### 3. Submit a review -The only way to submit a review within Atom is by using the "Submit review" button in the Pending Review tab. After publishing the review, the Pending Review tab will be destroyed. User will be led back to the All Reviews tab, which will immediately reflect the just published review. +The only way to submit a review within Atom is by using the ["Submit review" button in the Pending Review tab](#summary-section). After publishing the review, the Pending Review tab will be destroyed. User will be led back to the All Reviews tab, which will immediately reflect the just published review. ## 🤯 Components Explanation @@ -89,7 +89,7 @@ The comments section of the Pending Review tab looks very similar to that of the ### New Comment ![new comment](https://user-images.githubusercontent.com/6842965/56695406-fdd22700-66b6-11e9-9e7e-fe85e2507a66.png) -A new comment block can appear in either All Reviews tab or Pending Review tab, depending on the scenarios covered in "Add comment gutter icon" section below. When in focus, a new comment block always has a glowing border to emphasize itself. If there is already a pending review, there should only be one `btn-primary` button that reads "Comment". +A new comment block can appear in either All Reviews tab or Pending Review tab, depending on the scenarios covered in [the section below](#add-comment-gutter-icon). When in focus, a new comment block always has a glowing border to emphasize itself. If there is already a pending review, there should only be one `btn-primary` button that reads "Comment". ### "Add comment" gutter icon From 999af2f8cb2640873615e5dcb33dfc9cbdb93ddf Mon Sep 17 00:00:00 2001 From: Ash Wilson Date: Wed, 1 May 2019 17:45:37 -0400 Subject: [PATCH 16/19] Update docs/feature-requests/006-pull-request-reviewer-flow.md Co-Authored-By: vanessayuenn <6842965+vanessayuenn@users.noreply.github.com> --- docs/feature-requests/006-pull-request-reviewer-flow.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/feature-requests/006-pull-request-reviewer-flow.md b/docs/feature-requests/006-pull-request-reviewer-flow.md index 18a744d84d..a34cec2fcd 100644 --- a/docs/feature-requests/006-pull-request-reviewer-flow.md +++ b/docs/feature-requests/006-pull-request-reviewer-flow.md @@ -101,7 +101,7 @@ A user can start a review or add a comment to an existing pending review by clic The flow of starting a review or adding a comment from the gutter varies a bit depending on the state of reviews: -* If there is no reviews at all +* If there are no reviews at all 1. User clicks on "add comment" icon in gutter 2. *Pending Review* tab opens in empty state 3. New comment block is added to the Pending Review tab From 87b75592c25ead818502ad22eb0f6ae1df025357 Mon Sep 17 00:00:00 2001 From: Vanessa Yuen Date: Wed, 1 May 2019 18:06:44 -0400 Subject: [PATCH 17/19] update RFC based on comments --- .../006-pull-request-reviewer-flow.md | 20 +++++++------------ 1 file changed, 7 insertions(+), 13 deletions(-) diff --git a/docs/feature-requests/006-pull-request-reviewer-flow.md b/docs/feature-requests/006-pull-request-reviewer-flow.md index a34cec2fcd..99d6439086 100644 --- a/docs/feature-requests/006-pull-request-reviewer-flow.md +++ b/docs/feature-requests/006-pull-request-reviewer-flow.md @@ -38,16 +38,13 @@ The only way to submit a review within Atom is by using the ["Submit review" but ### "All Reviews" tab This tab shows all review summaries and review comments, including the ones that are part of a _pending review_ that has not been submitted yet. -#### Header -| current header | proposed header | proposed header with pending review | +#### Header tabs +| header with no pending review | header with pending review | |---|---| --- | -|old header|new header|new header| +|new header|new header| -- When there is no pending review, button reads "Start a review", clicking on which will take you to the Pending Review tab in its empty state. -- When there is already a pending review, the button reads "Resume review (2)". The number is a counter of comments currently in the pending review. When adding more pending comments _within the All Reviews tab_ (more on that flow below), there should be some emphasis on the counter changing -- akin to the button on dotcom. Clicking on this button takes user to the Pending Review tab. - -##### Alternative: footer -An alternative would be to add a footer bar at the bottom and place the add review button there. The caveat is that it might not be as noticeable as the header, and "start a new review" is an arguably more important action than "checkout". +- When there is no pending review, button reads "Start a new review", clicking on which will take you to the Pending Review tab in its empty state. +- When there is already a pending review, the button is replaced by a regular tab that reads "Pending Review (2)". The number is a counter of comments currently in the pending review. When adding more pending comments _within the All Reviews tab_ (more on that flow below), there should be some emphasis on the counter changing -- akin to the button on dotcom. #### Responding to a comment thread ![responding to a comment thread](https://user-images.githubusercontent.com/6842965/56689748-cdd05700-66a9-11e9-90e8-266c69cbc589.png) @@ -83,7 +80,7 @@ The summary section of the Pending Review tab is sticky (although still collapsi The comments section of the Pending Review tab looks very similar to that of the All Reviews tab, except that the progress bar is replaced by a small comment counter on top of the whole section. -**Empty State** of this section should contain a picture tutorial of how to add a comment via gutter icon. +**Empty State** of this section should contain a graphical tutorial of how to add a comment via gutter icon, along with a way to quickly navigate to the files changed tab so users can start adding comments right away. ### New Comment @@ -94,10 +91,7 @@ A new comment block can appear in either All Reviews tab or Pending Review tab, ### "Add comment" gutter icon -A user can start a review or add a comment to an existing pending review by clicking on the "add comment" icon which shows up on hover over the gutter of: - -1. MultiFilePatch view within Files tab in `PullRequestDetailView` -2. an editor *if on a checked out PR branch* +A user can start a review or add a comment to an existing pending review by clicking on the "add comment" icon which shows up on hover over the gutter of `MultiFilePatch` view within Files tab in `PullRequestDetailView`. The flow of starting a review or adding a comment from the gutter varies a bit depending on the state of reviews: From f790be87f4d140e557131ea70bb076e1a866cc8e Mon Sep 17 00:00:00 2001 From: Vanessa Yuen Date: Wed, 1 May 2019 18:55:30 -0400 Subject: [PATCH 18/19] fill in part 2 of RFC --- .../006-pull-request-reviewer-flow.md | 25 +++++-------------- 1 file changed, 6 insertions(+), 19 deletions(-) diff --git a/docs/feature-requests/006-pull-request-reviewer-flow.md b/docs/feature-requests/006-pull-request-reviewer-flow.md index 99d6439086..38f3714e13 100644 --- a/docs/feature-requests/006-pull-request-reviewer-flow.md +++ b/docs/feature-requests/006-pull-request-reviewer-flow.md @@ -115,36 +115,23 @@ The flow of starting a review or adding a comment from the gutter varies a bit d 3. New comment block is added to the Pending Review tab --------------------- - -**_Part 2 - Additional information_** - ## :anchor: Drawbacks -Why should we *not* do this? +None considered, since this is a crucial part of a holistic pull request review experience. ## :thinking: Rationale and alternatives -- Why is this approach the best in the space of possible approaches? -- What other approaches have been considered and what is the rationale for not choosing them? -- What is the impact of not doing this? - -## :question: Unresolved questions - -- What unresolved questions do you expect to resolve through the Feature Request process before this gets merged? -- What unresolved questions do you expect to resolve through the implementation of this feature before it is released in a new version of the package? +Since we have already decided and implemented review tab to _view_ PR review, it makes sense to extend the tab's functionality to include the capability of authoring a review. ## :warning: Out of Scope -- What related issues do you consider out of scope for this Feature Request that could be addressed in the future independently of the solution that comes out of this Feature Request? +- Allowing review comments to be left in regions _outside of_ the modified region of a PR +- Adding comments from editor instead of just from files changed tab in `PRDetailView` ## :construction: Implementation phases -- Can this functionality be introduced in multiple, distinct, self-contained pull requests? -- A specification for when the feature is considered "done." +An "edit comment" functionality will be needed for this feature. It can be a standalone piece that gets tackled separately, before starting the PR review authoring experience. ## :white_check_mark: Feature description for Atom release blog post -- When this feature is shipped, what would we like to say or show in our Atom release blog post (example: http://blog.atom.io/2018/07/31/atom-1-29.html) -- Feel free to drop ideas and gifs here during development -- Once development is complete, write a blurb for the release coordinator to copy/paste into the Atom release blog +TBD From b6c47894a69532a7fcf6f9dfe668125b494de4ac Mon Sep 17 00:00:00 2001 From: Vanessa Yuen Date: Wed, 1 May 2019 18:57:13 -0400 Subject: [PATCH 19/19] fix markdown table syntax --- docs/feature-requests/006-pull-request-reviewer-flow.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/feature-requests/006-pull-request-reviewer-flow.md b/docs/feature-requests/006-pull-request-reviewer-flow.md index 38f3714e13..3cc35472dd 100644 --- a/docs/feature-requests/006-pull-request-reviewer-flow.md +++ b/docs/feature-requests/006-pull-request-reviewer-flow.md @@ -40,7 +40,7 @@ This tab shows all review summaries and review comments, including the ones that #### Header tabs | header with no pending review | header with pending review | -|---|---| --- | +|---|---| |new header|new header| - When there is no pending review, button reads "Start a new review", clicking on which will take you to the Pending Review tab in its empty state.