Git-Mastery: Lessons

T9L1. Creating Pull Requests


To propose a contribution to a GitHub project, you can create a pull request.

This lesson covers that part.

A pull request (PR for short) is a mechanism for contributing code to a remote repo i.e., "I'm requesting you to pull my proposed changes to your repo". It's feature provided by RCS platforms such as GitHub. For this to work, the two repos must have a shared history. The most common case is sending PRs from a fork to its repo.

Suppose you want to propose some changes to a GitHub repo (e.g., samplerepo-pr-practice) as a pull request (PR).

HANDS-ON: Create a PR from the main branch

preparation samplerepo-pr-practice is an unmonitored repo that we have created for you to practice working with PRs.

  • Fork that repo onto your GitHub account.
  • Clone it onto your computer.
  • Commit some changes (e.g., add a new file with some contents) onto the main branch.
  • Push the branch you updated (i.e., main branch or the new branch) to your fork, as explained here.

1 Go to your fork on GitHub.

2 Click on the Pull requests tab followed by the New pull request button. This will bring you to the Compare changes page.

3 Specify the target repo and the branch that should receive your PR, using the base repository and base dropdowns. e.g.,
base repository: se-edu/samplerepo-pr-practice base: main

Normally, the default value shown in the dropdown is what you want but in case your fork has , the default may not be what you want.

4 Indicate which repo:branch contains your proposed code, using the head repository and compare dropdowns. e.g.,
head repository: myrepo/samplerepo-pr-practice compare: main

5 Verify the proposed code: Verify that the diff view in the page shows the exact change you intend to propose. If it doesn't, as necessary.

6 Submit the PR:

  • Click the Create pull request button.
  • Fill in the PR name and description e.g.,
    Name: Add an introduction to the README.md
    Description:
    Add some paragraph to the README.md to explain ...
Also add a heading ...
  • If you want to indicate that the PR you are about to create is 'still work in progress, not yet ready', click on the dropdown arrow in the Create pull request button and choose Create draft pull request option.
  • Click the Create pull request button to create the PR.
  • Go to the receiving repo to verify that your PR appears there in the Pull requests tab.

done!

The next step of the PR lifecycle is the PR review. The members of the repo that received your PR can now review your proposed changes.

  • If they like the changes, they can merge the changes to their repo, which also closes the PR automatically.
  • If they don't like it at all, they can simply close the PR too i.e., they reject your proposed change.
  • In most cases, they will add comments to the PR to suggest further changes. When that happens, GitHub will notify you.

You can update the PR along the way too. Suppose PR reviewers suggested a certain improvement to your proposed code. To update your PR as per the suggestion, you can simply modify the code in your local repo, commit the updated code to the same branch as before, and push to your fork as you did earlier. The PR will auto-update accordingly.

Sending PRs using the main branch is less common than sending PRs using separate branches. For example, suppose you wanted to propose two bug fixes that are not related to each other. In that case, it is more appropriate to send two separate PRs so that each fix can be reviewed, refined, and merged independently. But if you send PRs using the main branch only, both fixes (and any other change you do in the main branch) will appear in the PRs you create from it.

It is possible to create PRs within the same repo too e.g., you can create a PR from branch feature-x to the main branch, within the same repo. Doing so will allow the code to be reviewed by other developers (using PR review mechanism) before it is merged.

RESOURCES

DETOUR: Creating PRs from Other Branches

To create another PR while the current PR is still under review, you can create a new branch, add your new proposed change in that branch, and create a new PR using that branch instead of the main branch.

Steps for creating a PR from another branch is similar to how you created one from the main branch, except when sending the PR you should choose the other branch in place of the main branch.

DETOUR: Resolving Merge Conflicts in PRs

Merge conflicts can happen in ongoing PRs, when the receiving branch of the upstream repo has been updated in a way that the PR code conflicts with the latest version of that branch. GitHub indicates such conflicts with the message This branch has conflicts that must be resolved.

Here is the standard way to fix this problem:

  1. Pull the main branch from the upstream repo to your local repo.
    git checkout main
git pull upstream main
  2. In the local repo, attempt to merge the main branch (that you updated in the previous step) onto the PR branch, in order to bring over the new code in the main branch to your PR branch.
    git checkout pr-branch  # assuming pr-branch is the name of branch in the PR
git merge main
  3. The merge you are attempting will run into a merge conflict, due to the aforementioned conflicting code in the main branch. Resolve the conflict manually (this topic is covered elsewhere), and complete the merge.
  4. Push the PR branch to your fork. As the updated code in that branch no longer is conflicting with the main branch, the merge conflict alert in the PR will go away automatically.