About Pull Requests#
In the last lesson, you learned how to make and commit a change to a document in a GitHub repository. In this lesson, you will learn how to submit a pull request after making changes to a file in a GitHub repository.
A GitHub pull request (PR):
Allows you to suggest changes rather than making them directly to a repo you don’t own in a transparent way. You can’t break things by submitting a PR!
Supports Review: A pull request also triggers a review process where other repository owners and users can review and comment on your changes and suggest edits to your changes line-by-line. This makes incorporateing your changes fully transparent.
Maintainers to manage contributions: PRs allow maintainers to document, approve, and merge contributions into the project in a consistent way.
Social cue: A pull request is a collaborative tool—it lets maintainers review changes before merging them. PRs show transparency and let others give feedback, making sure every update aligns with the project’s goals.
Pull requests empower you to contribute to the work of others in an open and accessible way, even if you don’t have direct access to the repository.
How to Submit a GitHub Pull Request#
Step 1: Open your GitHub pull request#
To start a new pull request,click the New pull request button on the main page of your forked repository. Or, if you recently made a change to a branch in your fork, then GitHub will recognize is and prompt you to submit a PR (see the image below).
To create a pull request, go to the Pull Request tab in your account. Then click on the New pull request button.#
Tip
You will notice the Pull Request button in different places in the GitHub interface. Note that even tho you see the button on different pages, it does the same thing.
Animated gif showing that GitHub will prompt you to make a new pul request when it notices new commits to a branch in your fork.#
Step 2: Setup your pull request targets (head and base)#
When you setup your pull request, you will need to specify the head and the base. The head refers to the branch that is a-HEAD of the parent repository–ie a branch on your fork! The base is the parent repository that you wish to submit changes to.#
When creating a pull request (PR), you need to define where your changes should be added and where they come from.
Base: The repository where you want your changes to be merged. (This is usually the original repo you forked.)
Head: The repository containing your changes. (This is your fork. The copy of the repo that you own, where you made edits.)
🔹 Quick way to remember: The head is “ahead” of the base, meaning it has new changes that the base repository does not yet have.
In this example, you want to update:
base:
pyopensci/pyos-demo-package-contributewithhead: commits in your fork
your-username/pyos-demo-package-contribute.
Social Tip:
Choosing the correct head and base repositories ensures that your changes go to the right place. If you accidentally select the wrong base, your PR might not reach the maintainers you intended. Double-check this before submitting!
Step 3: Review your own pull request first#
When comparing repositories in a pull request (PR), GitHub provides a diff view of changes between files (diff as in difference). Before submitting the pr, carefully review these changes to ensure that what you intended to submit is in the PR (and nothing else).
Since others will review your PR, take time to clean up unnecessary changes before submitting. Your time upfront will lead to the PR being merged sooner and will make it easier for others to review.
Social cue:
A PR isn’t just about submitting changes—it’s about communicating clearly with maintainers. A well-reviewed PR with only relevant changes is easier to merge. Check that your PR doesn’t include unintended file modifications.
Before you submit your PR, check:
The number of files: Do they match what you intended to modify?
Review changes in each file: Are all modifications correct and expected?
When you first create a PR, be sure to check the PR contents. Notice that the number of files and commits are displayed in this image. Make sure these numbers make sense based upon the changes that you made.#
Exploring commits
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.
Step 4: Finalize and submit your PR#
Once you’ve reviewed your PR and everything looks good, it’s time to submit it.
Add a descriptive title and write a brief description of your changes. Pull request titles should be concise and descriptive of the content in the pull request. When you have added your title and description, click on “Create Pull Request” one more time to submit the PR.
Social cue:
A clear, descriptive PR title helps maintainers quickly understand your changes.
A good title is specific: “Fix typo in README” is better than “Updated file”.
Your description should also explain why the change was made.
If you go to the parent repository, you will see the PR listed there.
Tip
Take note that your pull request can be modified at any time, but do so with caution.
You can modify the title and description of your pull request even after you’ve submitted it.
New commits to your working branch will be visible in your open PR until they are merged.
Any changes made to it will potentially delay a review from maintainers. It’s best to submit the PR, review it, and leave it unchanged until you get feedback.
Close or move a Pull Request to draft#
Sometimes, after opening a pull request, you realize it’s not quite ready for review. In that case, you have two options:
Convert it to a draft – A draft pull request signals to maintainers that your PR is still in progress and not yet ready for review.
Close the PR – You can close a PR anytime via the Close pull request button and reopen it later when you’re ready to submit.
Who can merge a pull request?#
When you create a pull request (PR), GitHub directs you to the parent repository (e.g., the pyOpenSci repo). At the bottom of the PR, a Merge Pull Request button appears, which only the repository owner or collaborators can use after reviewing your changes.
Social cue:
Only maintainers can merge PRs, but you can make their job easier!
Be responsive if they ask for changes.
Follow repository guidelines for PR structure.
Check for review comments and update your PR accordingly.
The repo owner may request modifications before merging. Any future commits to the same branch will be added to the PR until it is merged.
You did it!
Once you’ve opened your pull request (PR), you wait for a response from the maintainer team! Congratulations on submitting a contribution to open source!