In this lab, you will pair up with another student to practice the GitHub fork and pull request workflow. This is the standard workflow for contributing to open source projects or any project where you don’t have write access to the repository.

Prerequisites

  • You should have completed Lab 2 and have a repository on GitHub with some content
  • Exchange GitHub repo and usernames with your lab partner

Lab objectives

In this lab you will:

  1. Fork your partner’s repository
  2. Clone it to your local machine
  3. Add the upstream remote
  4. Create a new branch
  5. Add a new file or make changes to an existing file
  6. Commit the changes
  7. Push the changes to your fork
  8. Submit a pull request to the original repository
  9. Review and merge your partner’s pull request

Step 1 - Fork your partner’s repository

  1. Browse to your partner’s repository on GitHub: https://github.com/<partner-username>/<inits>GitFun
  2. Select the Fork button in the top right corner
  3. In the Choose an owner dropdown, select your personal account
  4. Select the Create fork button

GitHub creates a copy of your partner’s repository in your account.

Step 2 - Clone your fork to your local machine

  1. In your terminal, navigate to your Git directory: cd ~/Git

  2. Clone your fork:

    git clone https://github.com/<your-username>/<repository-name>.git

    Alternatively, you can use the GitHub CLI:

    gh repo clone <your-username>/<repository-name>

  3. Change to the repository directory:

    cd <repository-name>

Step 3 - Add the upstream remote

This step links your local repository to the original repository (your partner’s repo). This allows you to pull changes from the original repository to keep your fork in sync. If you cloned the fork using the GitHub CLI, the upstream remote is added automatically. If you cloned using Git, you need to add the upstream remote manually:

git remote add upstream https://github.com/<partner-username>/<repository-name>.git

Verify the remotes:

git remote -v

You should see both origin (your fork) and upstream (your partner’s original repo).

Step 4 - Create a working branch

Always create a new branch for your changes. Never work directly on the main branch.

git checkout -b add-my-contribution

Step 5 - Make changes

Using Visual Studio Code, make some changes to the repository. Here are some ideas:

  • Add a new file called contributors.md and add your name
  • Add a new section to the README
  • Create a new file with some content related to the project
  • Fix a typo or improve existing documentation

Step 6 - Stage and commit your changes

git add -A
git commit -m "Add my contribution to the project"

Step 7 - Push your working branch to your fork

git push origin add-my-contribution

Step 8 - Submit a pull request

  1. Go to your partner’s original repository on GitHub: https://github.com/<partner-username>/<repository-name>/pulls
  2. Select the New pull request button
  3. Select compare across forks
  4. Set up the pull request:
    • Base repository: <partner-username>/<repository-name> base: main
    • Head repository: <your-username>/<repository-name> compare: add-my-contribution
  5. Fill out the pull request description:
    • Add a title (e.g., “Add contributions from [your name]”)
    • Add a description of what you changed and why
  6. Select Create pull request

Step 9 - Review your partner’s pull request

Now your partner should have submitted a pull request to YOUR repository. Let’s review and merge it:

  1. Go to your repository on GitHub
  2. Select on the Pull requests tab
  3. Select on your partner’s pull request
  4. Review the changes:
    • Look at the Files changed tab to see what was modified
    • Add comments if you have feedback
    • Select Review changes and select Approve
  5. Select Merge pull request
  6. Select Confirm merge
  7. Optionally, delete the branch after merging

Step 10 - Sync your local repository

After the PR is merged, update your local repository:

git checkout main
git pull origin main

Step 11 - Cleanup your working branch

Delete the branch you used for your contribution:

git push origin --delete add-my-contribution
git branch -D add-my-contribution

Bonus: Keep your fork in sync

As the original repository (upstream) receives changes, you’ll want to keep your fork updated:

git checkout main
git pull upstream main
git push origin main

Next ⏭