In this lesson, you will learn how to submit a pull request to suggest that your edits be included in another repository (e.g. the original repository from which you forked and cloned a repository). Specifcally, you will practice submitting a pull request for your updated
Jupyter Notebook for Homework 1.
After completing this lesson, you will be able to:
- Explain the relationship between a forked repository (head) and the original repository (base).
- Submit a pull request of changes to a repository on
What You Need
Be sure that you have also completed the Guided Activity on Version Control with Git/GitHub.
You will also need a web browser and your
GitHub.com login (username and password).
Step 1 - Fork The Repo
This step only needs to be done once. You begin by making a copy of the repo in your own account. This is called forking. When you make this copy you then have it available to you in your user account.
Clone the Repo
About Pull Requests
In the Guided Activity on Version Control with Git/GitHub, you added, committed, and pushed changed files to your forked repository on
To submit changed files to the original repository owned by earthlab-education (
https://github.com/earthlab-education/ea-bootcamp-hw-1-yourusername), you need to submit a pull request on
Pull requests inform the owner of the original repository (e.g.
https://github.com/earthlab-education/ea-bootcamp-hw-1-yourusername) that you have changed files you would like to add from a forked repository (e.g.
A pull request to another repository is similar to a “push”. However, it allows for a few things:
- It allows you to contribute to another repo without needing administrative privileges to make changes to the repository.
- It allows others to review your changes and suggest corrections, additions, edits, etc.
- It allows repository administrators control over what gets added to their project repo.
The ability to suggest changes to ANY repository, without needing administrative privileges is a powerful feature of
GitHub. 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.
Submit Pull Requests
This section was adapted from the
GitHub Hello World guide. They provide an animated version of these directions.
Pull requests are the heart of collaboration on
Github.com. When you open a pull request, you’re proposing your changes and requesting that someone review and pull in your contribution and merge them into their project.
Pull requests show diffs, (differences), of the content between your repo and the repo that you are submitting changes to. The changes, additions, and subtractions are shown in green and red.
Step 1 - Start Pull Request
To begin a pull request (PR), click the
New pull request button on the main page of your forked repository (e.g.
Data Tip: 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.
Step 2 - Select Repository to Update
Next, you need to select which repository you wish to update (the base repo) and which repository contains the content that you wish to use to update the base (the head repo).
In this example, you want to update
earthlab-education/ea-bootcamp-hw-1-yourusername with commits in your fork
Head vs Base
- Base: the repository that will be updated; changes will be added to this repository.
- Head: the repository containing the changes that will be added to the base.
One way to remember this is that the “head” is ahead of the “base”. So you must add from the head to the base.
When you begin a pull request, the head and base will auto-populate as follows:
- base fork:
- head fork:
The above pull request configuration tells
Github.com to update the base repository with contents from your forked repository, or the head repository.
Step 3 - Verify Changes
When you compare two repos in a pull request page,
GitHub provides an overview of the differences (diffs) between the files. Look over the changes and make sure nothing looks surprising.
You can also click on the commit titles to see the specific changes in each commit.
Step 4 - Create New Pull Request
If you are adding new commits to base repository (e.g.
earthlab-education/ea-bootcamp-hw-1-yourusername), then the “Create Pull Request” button will be available. Click the green “Create Pull Request” button to start your pull request.
Step 5 - Describe Your Pull Request
Add a title and write a brief description of your changes. When you’re done with your message, click “Create Pull Request”.
Notice that when creating a new pull request, you will be automatically transferred to the
Github.com site for the base repository.
At this point, you are done with the pull request! In this case, you have submitted a pull request for Homework 1!
Though you may see an active button for Merge Pull Request, this button is intended for the owner of the repository. They can review your pull request and then decide if/when to merge it into their original repository.
Note that until the owner merges your pull request, all future commits that you make to your fork will continue to be added to the open pull request.
Close Pull Requests
You can also close a pull request on
Github.com 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 if you have not yet completed Homework 1. When you are ready to submit Homework 1, you can simply create a new pull request on
Github.com following these same steps.
To close a pull request, simply click on
Close pull request button toward the bottom of the pull request page.
Congratulations! You know now how to submit Homework 1. Simply repeat the steps in this lesson when you are ready to submit your final
Jupyter Notebook file for Homework 1.