<commit_before># Pull Request Review

## Status

Accepted

## Summary

Give and receive code reviews on pull requests within Atom.

## Motivation

Workflows around pull request reviews involve many trips between your editor and your browser. If you check out a pull request locally to test it and want to leave comments, you need to map the issues that you've found in your working copy back to lines on the diff to comment appropriately. Similarly, when you're given a review, you have to mentally correlate review comments on the diff on GitHub with the corresponding lines in your local working copy, then map _back_ to diff lines to respond once you've established context. By revealing review comments as decorations directly within the editor, we can eliminate all of these round-trips and streamline the review process for all involved.

Peer review is also a critical part of the path to acceptance for pull requests in many common workflows. By surfacing progress through code review, we provide context on the progress of each unit of work alongside existing indicators like commit status.

## Explanation

### Pull Request list

![image](https://user-images.githubusercontent.com/378023/46524357-89bf6580-c8c3-11e8-8e2d-ea02d5a1f278.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.

![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.


### PullRequestDetailItem

#### Header

![header](https://user-images.githubusercontent.com/378023/46536358-3829d180-c8e9-11e8-9167-3d1003ab566b.png)

At the top of each `PullRequestDetailItem` is a summary about the pull request, followed by the tabs to switch between different sub-views.

- Overview
- Files (**new**)
- Reviews (**new**)
- Commits
- Build Status

Below the tabs is a "tools bar" for controls to toggle review comments or collapse files.

#### Footer

![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)


### Files (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.

![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.

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.


### 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

Hovering along the gutter within a pull request diff region in a `TextEditor` or a `PullRequestDetailItem` reveals a `+` icon. Clicking the `+` icon reveals a new comment box, which may be used to submit a single comment or start a multi-comment review:

![new review](https://user-images.githubusercontent.com/378023/46926996-49ec4100-d06e-11e8-9fb7-86607861efdd.png)

* Clicking "Add single comment" submits a diff comment and does not create a draft review.
* Clicking "Start a review" creates a draft review and attaches the authored comment to it.

##### Pending comments

![pending review](https://user-images.githubusercontent.com/378023/46927357-e06d3200-d06f-11e8-9eae-b4c289fe16ae.png)

* If a draft review is already in progress, the "Start a review" button reads "Add review comment".
* An additional row is added with options to "Start a new conversation" or "Finish your review".

##### Submit a review

Clicking "Finish your review" from a comment or clicking "Review Changes" in the footer...

![reviews panel](https://user-images.githubusercontent.com/378023/46536010-17ad4780-c8e8-11e8-8338-338bb592efc5.png)

... expands the footer to:

![submit review](https://user-images.githubusercontent.com/378023/46927736-ef54e400-d071-11e8-99d9-0ea1001fc50d.png)

* The review summary is a TextEditor that may be used to compose a summary comment.
* Files with pending review comments are listed and make it possible to navigate between them.
* A review can be marked as "Comment", "Approve" or "Recommend changes" (.com's "Request changes").
* Choosing "Cancel" dismisses the review and any comments made. If there are local review comments that will be lost, a confirmation prompt is shown first.
* Choosing "Submit review" submits the drafted review to GitHub.

##### Resolve a comment

![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.
* If the "reply..." editor has non-whitespace content, it is submitted as a final comment first.

#### 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".

Files | Reviews | Single file
--- | --- | ---
![files](https://user-images.githubusercontent.com/378023/46932382-6bf3bc80-d08a-11e8-83ce-af2ec99c3610.png) | ![reviews](https://user-images.githubusercontent.com/378023/46535563-c81a4c00-c8e6-11e8-9c0b-6ea575556101.png) | ![single file](https://user-images.githubusercontent.com/378023/46928308-e9accd80-d074-11e8-8de3-a16140e74907.png)

In order to navigate between comments or switch context, each comment has the following controls:

![image](https://user-images.githubusercontent.com/378023/46934191-c6444b80-d091-11e8-9405-b93bd2aecc90.png)

* 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 "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.

Another way to navigate between unresolved comments is to collapse all files first. Files that contain unresolved comments have a "[n] unresolved" button on the right, making it easy to find them.

![files with unresolved comments](https://user-images.githubusercontent.com/378023/46986769-022bef00-d12c-11e8-8839-279fb0d03fb1.png)
<commit_msg>Document using a "PullRequestReviewsItem" for review navigation.<commit_after># Pull Request Review

## Status

Accepted

## Summary

Give and receive code reviews on pull requests within Atom.

## Motivation

Workflows around pull request reviews involve many trips between your editor and your browser. If you check out a pull request locally to test it and want to leave comments, you need to map the issues that you've found in your working copy back to lines on the diff to comment appropriately. Similarly, when you're given a review, you have to mentally correlate review comments on the diff on GitHub with the corresponding lines in your local working copy, then map _back_ to diff lines to respond once you've established context. By revealing review comments as decorations directly within the editor, we can eliminate all of these round-trips and streamline the review process for all involved.

Peer review is also a critical part of the path to acceptance for pull requests in many common workflows. By surfacing progress through code review, we provide context on the progress of each unit of work alongside existing indicators like commit status.

## Explanation

### Pull Request list

![image](https://user-images.githubusercontent.com/378023/46524357-89bf6580-c8c3-11e8-8e2d-ea02d5a1f278.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.

![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

#### Header

![header](https://user-images.githubusercontent.com/378023/46536358-3829d180-c8e9-11e8-9167-3d1003ab566b.png)

At the top of each `PullRequestDetailItem` is a summary about the pull request, followed by the tabs to switch between different sub-views.

- Overview
- Files (**new**)
- Commits
- Build Status

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:

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)

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.

![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.

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

Hovering along the gutter within a pull request diff region in a `TextEditor` or a `PullRequestDetailItem` reveals a `+` icon. Clicking the `+` icon reveals a new comment box, which may be used to submit a single comment or start a multi-comment review:

![new review](https://user-images.githubusercontent.com/378023/46926996-49ec4100-d06e-11e8-9fb7-86607861efdd.png)

* Clicking "Add single comment" submits a diff comment and does not create a draft review.
* Clicking "Start a review" creates a draft review and attaches the authored comment to it.

##### Pending comments

![pending review](https://user-images.githubusercontent.com/378023/46927357-e06d3200-d06f-11e8-9eae-b4c289fe16ae.png)

* If a draft review is already in progress, the "Start a review" button reads "Add review comment".
* An additional row is added with options to "Start a new conversation" or "Finish your review".

##### Submit a review

Clicking "Finish your review" from a comment or clicking "Review Changes" in the footer...

![reviews panel](https://user-images.githubusercontent.com/378023/46536010-17ad4780-c8e8-11e8-8338-338bb592efc5.png)

... expands the footer to:

![submit review](https://user-images.githubusercontent.com/378023/46927736-ef54e400-d071-11e8-99d9-0ea1001fc50d.png)

* The review summary is a TextEditor that may be used to compose a summary comment.
* Files with pending review comments are listed and make it possible to navigate between them.
* A review can be marked as "Comment", "Approve" or "Recommend changes" (.com's "Request changes").
* Choosing "Cancel" dismisses the review and any comments made. If there are local review comments that will be lost, a confirmation prompt is shown first.
* Choosing "Submit review" submits the drafted review to GitHub.

##### Resolve a comment

![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.
* If the "reply..." editor has non-whitespace content, it is submitted as a final comment first.

### 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".

Files | Reviews | Single file
--- | --- | ---
![files](https://user-images.githubusercontent.com/378023/46932382-6bf3bc80-d08a-11e8-83ce-af2ec99c3610.png) | ![reviews](https://user-images.githubusercontent.com/378023/46535563-c81a4c00-c8e6-11e8-9c0b-6ea575556101.png) | ![single file](https://user-images.githubusercontent.com/378023/46928308-e9accd80-d074-11e8-8de3-a16140e74907.png)

In order to navigate between comments or switch context, each comment has the following controls:

![image](https://user-images.githubusercontent.com/378023/46934191-c6444b80-d091-11e8-9405-b93bd2aecc90.png)

* 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.
* 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.

Another way to navigate between unresolved comments is to collapse all files first. Files that contain unresolved comments have a "[n] unresolved" button on the right, making it easy to find them.

![files with unresolved comments](https://user-images.githubusercontent.com/378023/46986769-022bef00-d12c-11e8-8839-279fb0d03fb1.png)

{'fraction_non_alphanumeric': 0.0858269787010255, 'fraction_numerical': 0.0803050223507757, 'mean_word_length': 4.7139423076923075, 'pattern_counts': {'":': 0, '<': 8, '<?xml version=': 0, '>': 11, 'https://': 43, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3393756', 'n_tokens_mistral': 6473, 'n_tokens_neox': 5605, 'n_words': 2231}