---
title: Propose changes to GitHub repositories
subtitle: Create pull requests on GitHub
date: last-modified
author:
  - Leah Wasser
  - Max Joseph
  - Jenny Palomino
  - Elsa Culler
description: |
  A pull request allows anyone to suggest changes to a repository on GitHub
  that can be easily reviewed by others.
  Learn how to submit pull requests on GitHub.com to
  suggest changes to a GitHub repository.
learning-goals:
  - Explain what a pull request is and how it can be used.
  - Explain the difference between a branch and a fork
  - Explain the relationship between the head repository (e.g. a forked repository) and base (e.g. original repository or main branch) repository.
  - Mention or call out someone to review your pull request on **GitHub** using `@GitHubUsername`.
  - Explain what a diff is in **GitHub**.
  - Submit a pull request of changes to a repository on **GitHub.com**.
jupyter:
  jupytext:
    formats: 'ipynb,md'
  kernelspec:
    display_name: Python 3
    language: python
    name: python3
---

## Requesting changes to a repository

When you're collaborating with someone on GitHub, you'll find you want to be able to propose changes without actually making them to the default version. This is important for all collaboration (think about other online collaboration tools like Google Docs) -- but it is *especially* important for code, because one error can break the whole thing. You want to make sure that all the code works together as expected before merging. A **pull request** (referred to as a **PR**) is a way for you to **suggest** or **propose** changes to code in a GitHub repository. It allows you and your collaborators to:

  * See suggested changes side-by-side the original,
  * Leave comments on individual lines,
  * Discuss the changes
  * Run tests on the new code to make sure it works with everything else, and
  * Make sure that any suggestions adhere to group policies and norms,

all before making any official changes. Once everyone agrees on the changes, you can **merge** them in with the original.

Pull requests can be implemented in two ways, usually depending on what your relationship is with the project:

1. When you are part of a project team, you will usually develop changes on a **branch** within the team's repository.
2. When contributing to a project from the outside, you usually make your changes in a **fork** (i.e. copy owned by you) of that repository.

In either case, once you think your code is ready, it's polite to make a **pull request** rather than unilaterally making changes. That way your team can review what you've done! The ability to make changes in the **main** branch is usually restricted to just a few people.

## Branches and Forks

GitHub has two different methods for making changes, **branches** and **forks**. **Branches** are for when you are a part of the core team for a project. **Forks** are for when you are contributing to someone else's project. The key difference is that **you own your fork**, but you don't own a branch. This allows repository owners to protect their repository from outside collaborators a little more carefully.

After you have made changes in a branch or a fork, you can propose them to the administrators as a Pull Request or PR. 

## Introduction to the Pull Request Workflow

Suppose that you are working with your colleague, Alice, on a project. You have been asked to make some changes to a file in your collaborator's repository. Your workflow will look something like:

```{mermaid}
sequenceDiagram
  actor Alice
  participant Alice's Repository
  actor You
  participant Your Fork
  Alice-->>You: Hey, can you make a change to my repository?
  You-->>Alice: Sure! Let me go fork it!
  You->>Alice's Repository: Open up Alice's repository on GitHub
  activate Alice's Repository
  Alice's Repository->>Your Fork: Fork Alice's repository
  deactivate Alice's Repository
  activate Your Fork
  Your Fork->>Your Fork: Make a change
  Your Fork->>Alice's Repository: Create a Pull Request
  deactivate Your Fork
  You-->>Alice: Hey Alice -- I made a change!
  Alice-->>You: Oh, great! Let me check it out.
  Alice->>Alice's Repository: Review Pull Request
  activate Alice's Repository
  Alice-->>You: Looks good to me!
  Alice->>Alice's Repository: Merge Pull Request
  deactivate Alice's Repository
  Alice-->>You: Thanks, that was just what I needed!
```

### GitHub and Mentions: Communicating With Your Collaborators

After you have submitted your PR, your colleague can review the changes. It is good practice to "mention" your colleague specifically when you submit your PR to ensure that they see it. You can do that by using `@<their-github-username>` in a comment in the PR (e.g. `@eastudent` which will notify the GitHub user called `eastudent`). 

Your colleague will review the changes.  If they would like a few additional changes, they will request changes. 

Once your colleague is happy with the changes, then they will merge your PR.

## The Anatomy of a Diff (Difference Between Two Files)

**Git** keeps track of changes through additions and deletions on a character by
character and line by line basis.

So, pretend that the word "great" is spelled incorrectly in a file, and you wish
to fix the spelling. The edit that you will make is: **graet** is changed to **great**

The change above represents 2 character deletions and 2 additions.

The word great has 5 characters, so the number of characters is not changing in this example.

However, you are deleting: `ae` and replacing those two characters with `ea`.

As you edit files in a version control system like **git**, it is tracking each character
addition and deletion. These tracked changes are what you see in a diff when you submit a pull
request.

When you open up a pull request, you will see the line by line changes or differences between the file you submitted, compared to the file that exists in a repository. These changes are called **diffs** (short for differences).

Pull requests show diffs of the content between the branch and repository where you made changes, and the branch and repository that you are submitting changes to. The changes are shown in green and red. The color green represents additions to the file whereas red represents deletions.

![This screenshot shows a diff associated with a pull request. On the LEFT, you can see the text (highlighted with red) that was modified by the proposed pull request. The words that are dark red were the ones that were deleted. On the RIGHT, you can see the text (in green) that represents the proposed changes. The words that are darker green were added. In this example, the word **earthpy** was replaced with **matplotcheck** in the contributing.rst file of the repo.](/img/earth-analytics/git-version-control/github-diff-file.png)

## GitHub Pull Requests Support Open Science and Open Collaboration

A pull request (herein referred to as **PR**) is ideal to use as a collaboration
tool. A **PR** is similar to a “push” that you would make to a repository that
you own. However, a **PR** also allows for a few things:

1. It allows you to contribute to another repo without needing administrative privileges to make changes to the repository.
2. It documents changes as they are made to a repository and as they address issues. It also makes those changes easily visible to anyone who may want to see them.
3. It allows others to review your changes and suggest corrections, additions, and edits on a line by line basis to those changes as necessary.
4. It supports and documents conversation between collaborators on the project.
5. It allows repository administrators or code maintainers to control what gets added to the project repository.

Note if you do not own the repository that you wish to modify, a **PR** is the
only way that you can contribute changes to that repository.

This ability to suggest changes to ANY repository, without needing administrative
privileges is a powerful feature of **GitHub**. 

This workflow supports open science
because the entire process of updating content is open and supported by peer
review. You can make as many changes as you want in your fork, and then suggest
that the owner of the original repository incorporate those changes using a pull request.

## Pull Request Terminology - Head vs. Base

Consider the example above where you were submitting changes to the contributing.rst
file in your colleague's repo. After pushing the changes to your fork, you are ready to make a pull request to your colleague's repo.  

When submitting a pull request, you need to specify both where you'd like to suggest the changes (e.g. your colleague's repo) and where the changes are coming from (e.g. your fork or branch). 

There are two key terms that you should know to set this up in Github: 

  * **Base**: Base is the repository and branch that will be updated. Changes will be added to this repository via the pull request. Following the example above, the base repo is your colleague's repo.
  * **Head**: Head is the repository and branch containing the changes that will be added to the base. Following the example above, this is your repository (your fork of your colleague's repo).

One way to remember the difference between head and base is that the “head” is a**head** of the "base". Ahead means that there are changes in the head repo that the base repo does NOT have. 

So, you need to add the changes from the **head**
 (your forked repo) to the **base** (your colleague's repo).

When you begin a pull request, the head and base will auto-populate. It may
look something like this:

* base fork: `your-colleagues-username/project-name`
* head fork: `your-username/project-name`

Next, you will learn how to create a pull request in **GitHub**.

## How To Submit Pull Requests To Suggest Changes To Repositories

This section is an overview of the pull request process on GitHub. You can also check out our [forking](/pages/03-git-github/02-github-collaboration/06-pr-activity-fork.qmd) and [branching](/pages/03-git-github/02-github-collaboration/07-pr-activity-branch.qmd) PR activities for a hand's on experience.

![Short animated gif showing the steps involved with creating a pull request. When you setup your pull request, remember to ensure that the base is the repository that you wish to ADD change to. Your fork (or a branch) is where the changes currently exist (i.e. the head). When creating a new pull request, you should always check that the changes in your PR are the ones that you wish to submit. It's also good practice to ping or `@mention` a collaborator who you want to review and merge the PR if you know who that will be.](/img/earth-analytics/git-version-control/github-submit-pull-request-demo.gif "When you setup your pull request, remember to ensure that the base is the repository that you wish to ADD change to. Your fork (or a branch) is where the changes currently exist (i.e. the head). When creating a new pull request, you should always check that the changes in your PR are the ones that you wish to submit. It's also good practice to ping or `@mention` a collaborator who you want to review and merge the PR if you know who that will be.")

### Step 1 - Start to Open Your Pull Request on GitHub

To start a PR, click the `New pull request` button on the main page of your forked repository.

![Location of the new pull request button on the main page of an example forked repository.](/img/earth-analytics/git-version-control/github-create-new-pull-request.png)

::: {.callout-tip}
# Data Tip

There are many different ways to submit a pull request. You can also click the “Pull Requests” tab at the top of the main page of a repository to submit a pull request (PR). When the pull request page opens, click the “New pull request” button to initiate a PR. You can also click on the PR button in the repository that you are submitting changes to!
:::


### Step 2 - Select Repository That You Want to Update on GitHub

In this example, you are updating another repository with changes from your fork. 

Next, select both the repo that you wish to update (the base repo) and the
repo that contains the content that you wish to use to update the base
(the head repo).

In this example, you want to update:

* **base**: `your-colleagues-username/project-name` with
* **head**: commits in your fork `your-username/project-name`.

The above pull request configuration tells **GitHub** to update the base repository with contents from your forked repository, or the head repository.

### Step 3 - Verify The Changes In Your Pull Request

When you compare two repos in a pull request page, **GitHub** provides an overview of the differences (diffs) between the files. 

Carefully review these changes to
ensure that the changes that you are submitting are in fact the ones that you
want to submit.

1. First, look at the number of files. How many files did you modify? Do you see that many files listed in the **PR**?
2. Look over the changes made to each file. Do the changes all look correct (like
     changes that you committed to the repository)?

![When you first create a PR, be sure to check the PR contents. Notice in this image that the number of files and number of commits are displayed. Make sure these numbers make sense based upon the changes that you made.](/img/earth-analytics/git-version-control/github-pr-changes.png)

::: {.callout-tip}
# Data Tip
You can also click on the commit titles to see the specific changes in each commit. This is another way to check that the contents of a PR are what you expect them to be.
:::

This review of your own **PR** before submitting it is important. Remember that someone
else is going to take time to review your PR. 

Make sure that you take care of
cleaning up what you can FIRST, before submitting the PR.

### Step 4 - Click on the Create New Pull Request Button

The next step of the create PR process is to click the "Create Pull Request" button. Note that this button will NOT be available if you have not made changes in your repo (e.g. fork). 

Click the green “Create Pull Request” button to start your pull request. Once you do that, a title box and description box will be visible.

Add a title and write a brief description of your changes. When you have added your
title and description, click on “Create Pull Request”.

::: {.callout-tip}
# Data Tip
You can modify the title and description of your pull request at any time - even after you've submitted the pull request!
:::

![Pull request titles should be concise and descriptive of the content in the pull request. More detailed notes can be left in the comments box.](/img/earth-analytics/git-version-control/github-create-pull-request.png)

## Pull Requests and Your Location On GitHub

When you create a new pull request, you will be automatically transferred to the
**GitHub.com** URL or landing page for the base repository (your colleague's
repository). 

At this point, you have submitted your pull request!

At the bottom of your pull request, you may see an large green button that says
**Merge Pull Request**. This button will be used by owner of the
repository (your colleague or perhaps others working on this collaborative project)
to merge in your changes, when a review has been completed. 

The repo owner will
review your PR and may ask for changes. When they are happy with all of the changes, your PR could get merged!

::: {.callout-tip}
# Data Tip

All future commits that you make to your fork (on the branch where you are working) will continue to be added to the open pull request UNTIL it is merged.
:::

## How To Merge GitHub Pull Requests on GitHub

After you have submitted your PR, someone who owns or manages the repo where you
are submitting the PR will review it. At this point, they will either:

1. suggest that you make some changes to the PR or
2. merge the PR if they are happy with all of the changes that you made.

A screencast showing how this process works is below.

![Short animated gif showing the steps involved with merging a pull request. It's common for a reviewer to comment on your pull request and request changes. Once the reviewer is happy with the PR, they will merge it using the merge button on the bottom of the PR. It is important to note that you can only merge a PR in a repo in which you have permissions to merge.](/img/earth-analytics/git-version-control/github-merge-pull-request.gif "It's common for a reviewer to comment on your pull request and request changes. Once the reviewer is happy with the PR, they will merge it using the merge button on the bottom of the PR. It is important to note that you can only merge a PR in a repo in which you have permissions to merge.")


### How To Close Pull Requests on GitHub

You can also close a pull request on **GitHub** if you decide you are not
ready to submit your files from your forked repository to the original repository.

For example, the pull request you just created in this lesson can be closed anytime before it is merged. 

When you are ready to submit changes,
you can simply create a new pull request on **GitHub** following these same steps.

To close a pull request, click on `Close pull request` button towards the
bottom of the pull request page.

![Location of the Close pull request button on an example pull request page from jenp0277 to earthlab-education.](/img/earth-analytics/git-version-control/github-close-pull-request.png)