Provide more context when creating a Pull Request

[haacked]

When I go to create a Pull Request from within the GitHub extension, it would be helpful to have more context readily displayed to help me craft a PR message.

One thing that Desktop does that I like is if there is only one commit in the branch (as compared to the target), it'll pre-fill the form with that commit title and message. It's a nice touch.

But most of the time, I have many commits. It'd be nice to maybe see the last few commits below and a quick way to see the changes. Just enough to jog my memory and help me describe the PR.

[grokys]

This is definitely something we want to do!

Related #762, #767,

[shana]

#1221 adds an enhancement to pre-fill the title and body when there is only one commit, but we would really like to make this a better, more fleshed out experience!

Problem

Overview

Depending on where you are in development (and your workflow), PRs might often contain way more than one commit. Some of these commits contain meaningful information about the intentions of the changes, while other commits might just be "Fix typo". All this information is hard to retrieve when creating a PR, as it isn't accessible on the same screen as the PR Creation form, or if it is it isn't easily accessible.

User Impact

• A user has x commits in a branch and wishes to create a PR. They've described in the commit messages what the changes do. When they start the PR creation process, they should be able to transfer the relevant information into the PR body without having to jump to another view to see what the commit messages are and then manually retyping the relevant parts. This will help speed up and streamline the PR creation process and ensure that information is not lost in the process.

• Both users that defer to the commit messages as their primary source of information on a branch and users who defer to the PR body as the primary source of information will have a more equal access to the information and won't lose out on preferring one strategy over another.

Solution 1

Use the same strategy that git uses when squashing commits and pre-fill the PR body field with all the commit messages. The user can then manually edit the title and body as normal.

Potential problems, limitations, challenges

• If there's a lot of commits, it's going to be messy for the user to sort them out.
• It doesn't work very well for branches with many "Fix typo" commits.

Solution 2

Provide a list of all the commits on the branch on the same area as the PR creation form. Allow the user to select one of the commits to use as the title of the PR. Allow the user to select x commits for the body of the PR field, and copy over that information into the PR body field. The user can manually edit the title and body.

Potential problems, limitations, challenges

• What is the workflow for when there's already content in the body field and the user wants to copy over more data from commits?
• The UI will need to be clear on what the commit message is going to be used for (title or pr body)
• How does undo work in this scenario?
• How do we explain that you can copy over information from the commit list?

[shana]

@donokuda ☝️ UI challenge for you here, what do you think?

[donokuda]

Solution number 2 seems to make the most sense here. Couple of clarifying questions and thoughts:

• Is the problem that it's difficult and time-consuming to describe what changes are being proposed and why
  • For example, you might be solving a high-level problem, but there might be some lower level refactoring that you would want to call out in a description that might feel unrelated to the task at hand.
• Solution 2 seems to want to call out the commits. Is this so that an author can piece together a description with commit messages as a jumping off point, or does an author call out specific commits so that a reviewer can look at them more specifically?

Allow the user to select one of the commits to use as the title of the PR.

I'm a little curious on how often a branch will contain a commit that summarizes an entire feature. I would argue that we won't need to worry about the title at the moment. Instead, we have the description guide the author on what the title should be.

There's one last thing I'd also like to focus on as an additional solution:

Changed Files (and diffs!)

Overview

In addition to commits, the files that have been touched in a branch help tell the story of what types of changes are expected to go into the target branch. It also helps the author verify that there aren't any unintentional changes sneaking in.

User impact

• A developer could have a number of changed files to merge into a target branch. The content of what has changed (the diff) is usually what would be looked at by a reviewer with changes requested or approved. The diff also contains lower level implementation details that would help an author describe what changes they plan on bringing in.
• The diff of changed files is also useful for double checking work that's about to be reviewed by colleagues. Typos and unrelated changes are spotted at this point before opening up (and notifying) teammates of changes.

Solution: Show a list of files that have changed

By listing out the files that have changed, an author can glance and verify that these are changes that are meant to go into the pull request. Seeing what files have changed could also help infer what to write in the pull request description.

Potential problems, limitations, challenges

• What happens when there's a lot of commits and/or a lot of files changed? Would that affect how we should display the information?
• How many levels of folders could files be nested under? Would that number affect how much horizontal space we have (currently it seems like we don't have a lot of space.)

Solution: Allow viewing the diff between branches

Being able to view the diff between branches would help understand the changes being brought in as a whole and how multiple commits come together. Ideally, it should be quick to view changes for each file given that changes in one file might be related to changes in another file.

Potential problems, limitations, challenges

• I'm unsure what diffing capabilities we get out of the box with Visual Studio and their limitations
• What about files that might not be relevant to changes proposed (for example, files brought in by a package manager... This could be an opportunity to be tackled later.)