What Are GitHub Pull Requests?

When you write some code that you want to contribute to a repository, you create and submit a pull request. Your code contains some proposed changes to the target repository. A pull request is your way of offering these changes to the maintainer of the repository. It gives the repository maintainers an opportunity to review the changes and either accept them, reject them, or ask for more changes to be made.

Pushing code to GitHub

The first thing to do is create a new branch. Creating a new branch before writing new code is standard operating procedure with Git.

A pull request doesn’t consist of an arbitrary set of changes or commits. A pull request is always associated with a branch. In other words, a pull request is a request to merge one branch into another.

While it’s true that a pull request can target any branch (except itself), the most common scenario is to target the main branch of a repository, typically named master.

$ git checkout -b <em>new-work</em>

Now that we have a branch, we need to create a commit in that branch. For this example, the specific contents of the commit are not important. You can choose any file and make some edits to the file, such as adding some text to the end. Or manually edit the README.md file manually or run the following command to append some text to end of the file:

$ echo "\n## Installation" >> README.md

Now that you have a file with some changes, commit those changes. You can use the following command, for example, to commit all your changes. The commit message is not important here. The important thing is to have a commit in a branch to work with that is not in the master branch.

$ git add -A

$ git commit -m "Add text to the README"

Now push this new branch to GitHub.com (replace new-work with your branch name):

$ git push -u origin new-work

The git push command tells Git to push local commits to a remote repository. The -u flag specifies where to push it — in this case, to a branch also named new-work on the remote named origin.

The -u flag is only needed the first time you push a new branch to the server. From that point on, the new-work branch on your local machine is associated with the new-work branch on GitHub.com and any subsequent pushes to that branch do not need the flag.

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

Repository home page with recently pushed branches listed.

Click the Compare & pull request button to navigate to the Open a pull request page, as shown in the following figure. 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. The following figure shows an example description.

The Open a pull request page.

You can change the default branch by choosing Settings→Branches section of your repository.

The pull request

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.

How to add reviewers

The first one, Reviewers, lets you specify one or more people that you want to review your pull request. To add reviewers:

1. 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.
2. 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. The following figure shows the reviewers list with two reviewers selected.

List of potential reviewers with two reviewers selected.

How to specify assignees

To specify assignees:

1. Click the gear to see a list of assignees. The assignee dialog box works just like the reviewers dialog box. It allows you to select one or more assignees.
2. 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.

How to specify labels

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.

Specify projects and milestones

How to create the pull request

A created pull request.