You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on Dec 15, 2022. It is now read-only.
@@ -18,69 +18,127 @@ Peer review is also a critical part of the path to acceptance for pull requests
18
18
19
19
## Explanation
20
20
21
-
### Current pull request tile
21
+
### Review information in Pull Request list
22
22
23
-
Reviews on the current pull request are rendered as a list on the current pull request tile.
23
+
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 it's own section at the top of the list.
Note: Change "Current pull request" to "Checked out pull request"
26
27
27
-
* The review summary bubble is elided after the first sentence or N characters if necessary.
28
-
* Clicking the review summary bubble opens an `IssueishDetailItem` in the workspace center.
29
-
* Clicking a line comment opens or activates an editor on the referenced file and scrolls to center the comment's line, translated according to local changes if appropriate.
30
-
* Line comments within the review are rendered: _with a vertical blue bar_ before the file has been opened and the corresponding decoration is visible; _with a vertical grey bar_ after the file and decoration have been seen; and _with a vertical green bar_ after the comment has been marked "resolved" with the control on its decoration.
31
-
* The review summary bubble and line comment lists are greyed out if a different `IssueishDetailItem` is activated.
28
+
Clicking a pull request in the list opens a `PullRequestDetailItem` in the workspace center.
32
29
33
-
If a pending review is present, it appears at the top of the "Reviews" section within this tile:
30
+
For PRs that are not listed in the panel, users can use the `github:open-issue-or-pull-request` command:
Each `PullRequestDetailItem` opened on a pull request displays the full, multi-file diff associated with the pull request. Review comments are shown within the diff. See ["Comment decorations"](#comment-decorations) for description of review comments.
38
+
39
+
40
+
41
+
TODO: update mock to have "Start review button" and "Add single comment"
42
+
43
+
Diffs are editable ONLY if the pull request branch is checked out and the local branch history has not diverged from the remote branch history. Otherwise diffs are not editable. Details of this will be fleshed out in a separate RFC specifically for editable diffs.
44
+
45
+
A panel at the bottom of the pane offers various options for sorting and filtering the diff. It also has a "Review Changes" button.
Note: We probably want to find better verbiage than "sort". Let's also consider a dropdown menu UX to select different views of the data.
52
+
53
+
The default view is sorted by files. This is akin to the "Files changed" tab on dotcom. It displays the diff for all changed files in the PR.
54
+
55
+
Sorting by reviews is akin to the review summaries that appear on the "Conversation" tab on dotcom. The comments are displayed grouped by review along with some context lines.
56
+
57
+
58
+
59
+
TODO: include show multiple reviews stacked
60
+
61
+
Sorting by commits is akin to the "Commits" tab on dotcom. A list of commits is displayed in chronological order, oldest commit on top. Clicking a commit expands the diff contents below. If there is a commit message body this is displayed as well. Commit diffs are not editable.
62
+
63
+
TODO: include commit sort mockup
64
+
65
+
A banner at the bottom of the pane offers navigation to individual files within the diff and to individual review comments, allows each review to be hidden or shown with a filter control, and shows a progress bar that counts "resolved" review comments. The banner remains visible as you scroll the pane.
The default is to show all files, all authors, and unresolved comments.
72
+
73
+
Filtering based on file type limits the diff view to displaying only that file type.
74
+
75
+
TODO: Consider adding a "Find" input field that allows us to filter based on search term (which could be a file name, an author, a variable name, etc). Probably out of scope for this RFC.
76
+
77
+
Clicking an author's avatar displays only their review information.
78
+
79
+
Clicking "unresolved" shows only resolved comments, helping users stay focused on comments that need to be addressed.
80
+
81
+
Clicking "resolved" shows only resolved comments. This allows users to quickly see what has already been addressed.
82
+
83
+
Checking "all comments" shows both resolved and unresolved comments.
84
+
85
+
Clicking "none" hides all comments, in the event that users want to see diff information only.
* The review summary is a TextEditor that may be used to compose a summary comment.
38
98
* 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.
39
99
* Choosing "Submit review" submits the drafted review to GitHub.
40
100
41
-
If there is no pending review, the tile instead displays a control to create one.
101
+
#### Summary Box
42
102
43
-
### IssueishDetailItem
103
+
At the top of the pane is the existing summary box:
44
104
45
-
Each `IssueishDetailItem` opened on a pull request displays the full, multi-file diff associated with the pull request.
TODO: add conversation/timeline icon and progress bar
46
107
47
-
A banner at the top of the pane offers navigation to individual files within the diff and to individual review comments, allows each review to be hidden or shown with a filter control, and shows a progress bar that counts "resolved" review comments. The banner remains visible as you scroll the pane.
108
+
Clicking on the "22 commits" opens the commit view and changes the bottom panel to indicate sort by commits.
48
109
49
-
At the top of the pane is the existing summary box:
110
+
Clicking on the "1 changed files" opens the files view and changes the bottom panel to indicate sort by files and "all files" checked.
Clicking on the build status summary icon (green checkmark, donut chart, or X) expands an ephemeral panel beneath the summary box showing build review status. Clicking the icon again or clicking on "dismiss" dismisses it.
52
113
53
-
* Clicking on the build status summary icon (green checkmark, donut chart, or X) expands an ephemeral panel beneath the summary box showing build review status. Clicking the icon again or clicking on "dismiss" dismisses it.
54
-
* Clicking on the commit count opens the log view to those commits.
Summary comments for each existing review appear in a list below that. If a pending review is being drafted, it appears at the end of the list; otherwise, a control is present to create one. A pending review may be finalized by submitting a form that appears adjacent to it.
116
+
Clicking on the conversation/timeline icon expands an ephemeral panel beneath the summary box showing a very timeline view. The PR description and PR comments are displayed here. Other note-worthy timeline events are displayed in a very minimal fashion. At the bottom is an input field to add a new PR comment.
57
117
58
-
After the summary comments, the diff is shown, with review comments in place:
Clicking the "expand" icon on the top right opens this information in a new pane to the right for easy side-by-side viewing with the diff (much like our current markdown preview opens in a separate pane).
61
121
62
-
On each review comment decoration:
122
+
TODO: add conversation/timeline pane item
63
123
64
-
* The up and down arrow buttons quickly scroll to center the next or previous comment within this tab.
65
-
* Clicking the "code" (`<>`) button opens the corresponding file in a TextEditor and scrolls to the review comment decoration there. If the current pull request is not checked out, the "code" button is disabled, and a tooltip prompts the user to check out the pull request to edit the source.
66
-
* Reaction emoji may be added to each comment with the "emoji" button. Existing emoji reaction tallies are included beneath each comment.
67
-
* Clicking "mark as resolved" marks the comment as resolved with on GitHub. If the "reply..." editor has non-whitespace content, it is submitted as a final comment first.
68
-
* The "comment" button is disabled unless the "reply" editor is expanded and has non-whitespace content.
69
-
* Clicking "comment" submits the response as a new stand-alone comment on that thread.
124
+
Clicking on the a commit takes you to the commit view and expands the selected commit, centering it in view.
70
125
71
-
Hovering in the diff's gutter reveals a `+` icon that allows users to begin creating a new pending review, or making an isolated comment, using the same UI described in ["In-editor decorations"](#in-editor-decorations). If a pending review is present, its comments are also shown and editable here.
126
+
TODO: add commit view mockup
72
127
73
-
### In-editor decorations
128
+
Clicking on a review reference takes you to the review view and expands the selected review, centering it in view.
74
129
75
-
When opening a TextEditor on a file that has been annotated with review comments on the current pull request, a block decoration is used to show the comment content at the corresponding position within the file content. Also, a gutter decoration is used to reveal lines that are included within the current pull requests' diff and may therefore include comments.
Within the multi-file diff view, a block decoration is used to show the comment content at the corresponding position within the file content.
80
136
81
137
* The comment's position is calculated from the position acquired by the GitHub API response, modified based on the git diff of that file (following renames) between the owning review's attached commit and the current state of the working copy (including any local modifications). Once created, the associated marker will also track unsaved modifications to the file in real time.
82
-
* The up and down arrow buttons navigate to the next and previous review comments within this review within their respective TextEditors.
83
-
* The "diff" button navigates to the corresponding pull request's `IssueishDetailItem` and scrolls to center the same comment within that view.
138
+
* The up and down arrow buttons navigate to the next and previous review comments.
139
+
* For comment decorations in the `PullRequestDetailItem`, clicking the "code" (`<>`) button opens the corresponding file in a TextEditor and scrolls to the review comment decoration there.
140
+
* If the current pull request is not checked out, the "code" button is disabled, and a tooltip prompts the user to check out the pull request to edit the source.
141
+
* Reaction emoji may be added to each comment with the "emoji" button. Existing emoji reaction tallies are included beneath each comment.
84
142
85
143
Hovering along the gutter within a pull request diff region reveals a `+` icon, which may be clicked to begin a new review:
86
144
@@ -91,25 +149,36 @@ Clicking the `+` reveals a new comment box, which may be used to submit a single
* If a draft review is already in progress, the "Add single comment" button is disabled and the "Start a review" button reads "Add review comment".
94
-
* Clicking "Add single comment" submits a non-review diff comment and does not create a draft review.
95
-
* Clicking "Start a review" creates a draft review and attaches the authored comment to it.
152
+
* Clicking "Add single comment" submits a non-review diff comment and does not create a draft review. This button is disabled unless the "reply" editor is expanded and has non-whitespace content.
153
+
* Clicking "Start a review" creates a draft review and attaches the authored comment to it. This button is disabled unless the "reply" editor is expanded and has non-whitespace content.
154
+
* Clicking "mark as resolved" marks the comment as resolved with on GitHub. If the "reply..." editor has non-whitespace content, it is submitted as a final comment first.
96
155
97
156
## Drawbacks
98
157
99
158
This adds a substantial amount of complexity to the UI, which is only justified for users that use GitHub pull request reviews.
100
159
101
-
Showing all reviews in the current pull request tile can easily overwhelm the other pull request information included there. It also limits our ability to expand the information we provide there in the future (like associated issues, say).
102
-
103
160
Rendering pull request comments within TextEditors can be intrusive: if there are many, or if your reviewers are particularly verbose, they could easily crowd out the code that you're trying to write and obscure your context.
104
161
105
162
## Rationale and alternatives
106
163
164
+
Our original design looked and felt very dotcom-esque:
We decided to switch to an editor-first approach and build the code review experience around an actual TextEditor item with a custom diff view. We are breaking free of the dotcom paradigm and leveraging the fact that we are in the context of the user's working directory, where we can easily update code.
169
+
170
+
We discussed displaying review summary information in the GitHub panel in a ["Current pull request tile"](https://github.com/atom/github/blob/2ab74b59873c3b5bccac7ef679795eb483b335cf/docs/rfcs/XXX-pull-request-review.md#current-pull-request-tile). The current design encapsulates all of the PR information and functionality within a `PullRequestDetailItem`. Keeping the GitHub panel free of PR details for a specific PR rids us of the problem of having to keep it updated when the user switches active repos (which can feel jarring). This also avoids confusing the user by showing PR details for different PRs (imagine the checked out PR info in the panel and a pane item with PR info for a separate repo). We also free up space in the GitHub panel, making it less busy/overwhelming and leaving room for other information we might want to provide there in the future (like associated issues, say).
171
+
107
172
<!-- Ongoing --->
108
173
109
174
## Unresolved questions
110
175
111
176
### Questions I expect to address before this is merged
112
177
178
+
When there are working directory changes, how do we clearly indicate them within the diff view? Do we need to make them visually distinct from the PR changes? Things might get confusing for the user when the diff in the editor gets out of sync with the diff on dotcom.
179
+
Example:
180
+
* Author reads comment pointing out typo in an added line. Author edits text in multi-file diff which modifies the working directory. Should this line now be styled differently to indicate that it has deviated from the original diff?
181
+
113
182
Can we access "draft" reviews from the GitHub API, to unify them between Atom and GitHub?
114
183
115
184
*_Yes, the `reviews` object includes it in a `PENDING` state._
@@ -142,10 +211,13 @@ How do we handle comment threads?
142
211
143
212
What other pull request information can we add to the GitHub pane item?
144
213
145
-
Are there other tabs that we need within the `IssueishDetailItem`?
146
-
147
214
How can we notify users when new information, including reviews, is available, preferably without being intrusive or disruptive?
0 commit comments