Problem

Overview

What should the review flow for pull requests look like? The main complexity here is that we have, at a minimum, three kinds of users coming in with different mental models.

Green Witch just wants to make a comment on a PR.

Bald Witch knows about Reviews (as a clustering of comments) from the web and wants to create them explicitly.

Boy Witch wants the behavior of Reviews (grouping many comments and not spamming their reviewees) but doesn't know what they are.

We'd like to keep them all happy (because if we don't they will ritually sacrifice us and eat our souls, just as they did to Macbeth—poor guy, but he really had it coming).

User Impact/High Level Use Cases

As Green Witch, I can add one-off comments to a PR
As Boy Witch, I can avoid spamming my co-workers with notifications. (This despite the fact that Boy Witch doesn't know what Reviews are, coming in.)
As Bald Witch, I can indicate that multiple changes are needed for my approval.

Justification

Users are asking for this functionality, and we have it on the web. If you have a lot of comments, the current review flow is pretty unfriendly—you end up spamming your coworkers.

Discussion & Mocks

After some faffing about trying to make the flow work with just one button, I think we should probably just have two: Send and Start Review.

We can workshop the names, but something I like about these is that (1) they're relatively short, and (2) it's obvious that send puts something on the server.

This arrangement makes Send feel like the default action. We may want to flip and de-emphasize it, if we want to encourage people to create reviews.

I also think that starting another comment should do the same thing as clicking Start Review. That is, a "Review" is just one or more comments that are sitting there in a draft state. The key point here is discoverability: if I want to make multiple comments before Sending them all out, but reviews sound strange and foreign to me, then I might try... creating multiple comments without clicking send. If we make that work, we then provide an on-ramp for people to discover what reviews are, and why they're useful.

Once a comment has been added to a review, we should show it inline, just as we do other comments, but with some clear indicator it's a draft:

Then when I add another comment, the options presented should be a little different:

Here, we want to make it clear that we're in a different state—specifically, that there's a review pending, and that comments are, preferentially, added to the review.

Finally, clicking any of the Draft badges or going to the Description page will show me my pending review:

We may want to workshop the buttons on this page, but that's the general idea.