Before you can open a pull request, your GitHub.com repository must have at least one branch other than the default branch. If you follow the steps in the earlier section “Pushing Code to GitHub,” you have a branch that is not yet merged into master. In our case, the branch is named new-work branch, but you may have named yours something else. Visit the repository on GitHub.com to open a pull request.
When you visit the repository on GitHub.com, you see a new message in the section labeled Your recently pushed branches, as shown in Figure 8-1.
Click the Compare & pull request button to navigate to the Open a pull request page, as shown in Figure 8-2. The target branch (the branch you want to pull your changes into) is the default branch for the repo. Your branch is listed next to the target branch, and a status of whether your branch can be merged into the target branch is next to that. The pull request title is the same as the most recent commit message — in this example Add text to the README — and your description is blank. Figure 8-2 shows an example description.
You can change the default branch by choosing Settings o Branches section of your repository.
GIT ALIAS FOR OPENING GITHUB.COM FROM THE TERMINAL
Often when working with a repository in the terminal, you need to jump to the repository on GitHub.com. I have an alias just for this purpose. Chapter 6 covers aliases in more details and how to add them. You can run the following in the terminal to add a new git browse alias.
$ git config —global alias.browse ‘!open ‘git config remote.origin.url’1
To use the alias, just run the following in the terminal from within your repository directory.
$ git browse
This code launches your default browser and navigates to your repository’s origin URL. This alias assumes you’re using https for your git remotes and not SSH.
GIT ALIAS FOR OPENING THE BRANCH COMPARE WEB PAGE
If, for some reason, the branch for which you want to create a pull request isn’t listed in the recently pushed branches section, you can navigate to the Compare page for your branch, which has the format https://gitub.com/{owner}/{repo}/compare/ {BRANCH}. As luck would have it, I have an alias for that:
$ git config —global alias.pr ‘!f(){ URL=$(git config remote.origin.url);
open ${URL%.git}/compare/$(git rev-parse —abbrev-ref HEAD); }; f’
$ git pr
Just as with the git browse alias earlier in the sidebar “Git Alias for opening GitHub.com from the terminal”, this alias assumes you use HTTPS URLs for your remotes and not SSH.
1. Describing the pull request
From the Open a pull request page, you can enter a summary and description. Chapter 7 covers some GitHub conventions for commit messages. Most of those conventions are also supported in a pull request — for example, mentioning people using the @USERNAME format. In Figure 8-2, I mention @sarah-wecan. When I create the pull request, @sarah-wecan receives a notification.
You can reference issues and other pull requests using the #ISSUEID format. And, of course, you can add emojis, such as :sparkles:.
In this section, we cover what to write here in more detail. There’s a lot that goes into a good pull request.
2. Adding reviewers
To the right of the pull request summary and description fields is a set of options for the pull request.
The first one, Reviewers, lets you specify one or more people that you want to review your pull request. To add reviewers:
- Click the gear to see a list of people you can mention.
For repositories with a large number of users, you can start typing to filter the set of users.
- Click each user to add them to the list of reviewers.
When you add a reviewer, they’re immediately notified when you finish creating the pull request. Figure 8-3 shows the reviewers list with two reviewers selected.
3. Specifying assignees
The next option after Reviewers is an option to specify assignees. An assignee is the person who should take action on the pull request. Often, a pull request represents a work in progress and not the final result of some work. If more work needs to be done on a pull request, you’d assign the pull request to the person that should do the work.
To specify assignees:
- Click the gear to see a list of assignees.
The assignee dialog box works just like the reviewers dialog box, described in the preceding section. It allows you to select one or more assignees.
- Click each user to add them to the list of reviewers.
In most cases, it’s best to just assign one person who will be responsible for the next step. Assigning one person reduces the chances that multiple assignees all think the other assignees are responsible for the work. ip
4. Specifying labels
Chapter 3 introduces labels on issues as a way to figure out what to work on next. Labels work the same way for pull requests. They provide convenient grouping and context to help you decide what to work on next or what to review next.
The set of labels you can use on issues and pull requests are the same, but some labels make more sense for issues than pull requests and vice versa. For example, many repositories have a “ready for review” label specifically for pull requests.
5. Specifying projects and milestones
The last two options allow you to specify the project board and milestone that this pull request belongs to. Chapter 3 covers projects, and Chapter 11 covers milestones.
6. Creating the pull request
After you have the pull request written and specified all the pull request options, click the Create pull request button to save all your work and create the pull request. Figure 8-4 shows a pull request I created on my repository.
Source: Guthals Sarah, Haack Phil (2019), GitHub for Dummies, Wiley.