Companion Podcast and Transcript

Use audio and transcript companions to review concepts in a conversational format.

Fork and Contribute

Companion audio: this episode reinforces key ideas and may not be a word-for-word reading of this page.

Open audio file (external) Full transcript source (external)

Transcript preview

Alex: Welcome back. Today we're taking the open source workflow all the way from a fork to a pull request that maintainers can review.

Jamie: This is the one that can feel intimidating, because suddenly you're not working in a classroom repository anymore. You're contributing to something someone else owns.

Alex: Exactly. A fork is your personal copy of someone else's repository on GitHub. It lives under your account, so you can push branches and experiment there without changing the original project.

Jamie: So forks are really about permission. I may not be allowed to write to the main project, but I can still do useful work in my copy.

Fork and Contribute: The Open Source Workflow

Related appendices: Appendix E: Advanced Git | Appendix O: Branch Protection | Appendix D: Git Authentication Authoritative sources: GitHub Docs: Fork a repo | GitHub Docs: Syncing a fork | Open Source Guides: How to Contribute

Day 2, Block 3 Material

This chapter teaches the complete fork-based contribution workflow from start to finish. You will fork a real repository, create a feature branch, make changes, push to your fork, and open a pull request against the upstream repository. This is the workflow used by millions of open source contributors every day, and it is the foundation for the capstone project in Chapter 20.

Table of Contents

  1. What Is a Fork?
  2. Fork vs Clone vs Branch
  3. Step 1: Fork the Repository
  4. Step 2: Clone Your Fork Locally
  5. Step 3: Add the Upstream Remote
  6. Step 4: Create a Feature Branch
  7. Step 5: Make Your Changes
  8. Step 6: Push to Your Fork
  9. Step 7: Open a Pull Request
  10. Step 8: Respond to Review Feedback
  11. Keeping Your Fork in Sync
  12. The Fork Workflow Checklist
  13. If You Get Stuck

Challenge 16: Capstone Project uses this fork-based workflow when your chosen repository accepts pull requests. Practice it here so the capstone feels familiar.

1. What Is a Fork?

See also: Chapter 08: Open Source Culture for the cultural context of forking and contributing.

A fork is your personal copy of someone else's repository on GitHub. When you fork a repository, GitHub creates a full copy under your account. You own the fork -- you can push to it, create branches on it, and modify it freely without affecting the original.

The original repository is called the upstream repository. Your fork is linked to the upstream, which means you can open pull requests from your fork back to the original.

Why forks exist

Forks solve a permissions problem. Most open source projects do not give every contributor write access to the main repository. Instead:

  1. You fork the project (creates your copy)
  2. You make changes on your copy
  3. You open a pull request asking the maintainers to merge your changes

This way anyone can contribute without the maintainers giving out write access.

The Day 1 connection: On Day 1, you worked in the learning-room repository where you had write access. You created branches directly on the repository. In the open source world, you usually do not have write access to the upstream repository, so you fork first and branch on your fork.

2. Fork vs Clone vs Branch

These three concepts are related but different. Understanding the distinctions prevents confusion.

Concept Where it lives What it creates When to use it
Fork GitHub.com (your account) A copy of the entire repository under your GitHub account When you want to contribute to a repo you do not own
Clone Your computer A local copy of any repository (yours or someone else's) When you want to work locally
Branch Inside any repository (local or remote) A named pointer to a specific commit When you want to isolate a change within a repository

How they work together

In the fork workflow, you use all three:

  1. Fork the upstream repository to create your copy on GitHub
  2. Clone your fork to your computer
  3. Create a branch on your local clone for your specific change
  4. Push the branch to your fork and open a PR to the upstream
Upstream repo (GitHub)      Your fork (GitHub)        Your computer (local)
+-------------------+       +-------------------+      +-------------------+
| Community-Access/ |  fork | your-username/    | clone|                   |
| accessibility-    | ----> | accessibility-    | ---> | accessibility-    |
| agents            |       | agents            |      | agents            |
+-------------------+       +-------------------+      +-------------------+
        ^                          ^                           |
        |                          |                           |
        +--- PR (fork to upstream) +--- git push              |
                                                      edit, stage, commit

Screen reader note: The text diagram above shows three boxes arranged left to right. The upstream repo on GitHub is on the left. Your fork on GitHub is in the middle. Your local computer is on the right. A fork arrow goes from left to middle. A clone arrow goes from middle to right. Editing happens on the right. Git push goes from right to middle. A PR goes from middle to left.

Learning Cards: Fork vs Clone vs Branch

Screen reader users
  • Run git remote -v in the terminal to hear your configured remotes -- origin is your fork, upstream is the original repository
  • The Status Bar in VS Code shows the current branch name -- press F6 to navigate there and confirm you are on a feature branch, not main
  • Use Ctrl+Shift+P then "Git: Checkout to" to switch between branches; your screen reader announces each branch name in the picker
Low vision users
  • Your fork URL includes your username (e.g., github.com/your-name/repo) making it visually distinct from the upstream URL
  • In VS Code, the branch name in the bottom-left Status Bar confirms which branch you are working on -- zoom with Ctrl+= if it is too small
  • The Source Control panel heading shows the repository name to help you verify you are working in the correct clone
Sighted users
  • On GitHub.com, forked repos show a "forked from" label under the repository name at the top of the page
  • The fork icon (a branching arrow) appears next to forked repository names in your GitHub profile
  • In VS Code, the bottom-left branch name and the Source Control panel header confirm your current branch and repository

3. Step 1: Fork the Repository

Tool Cards: Fork and Clone a Repository

github.com (browser):

  1. Click Fork on the repository page > Create fork.
  2. Clone: click the green Code button > copy URL > paste into your local tool.

VS Code Desktop:

  1. Fork on github.com first (browser required for forking).
  2. Ctrl+Shift+P > Git: Clone > paste your fork's URL.

GitHub Desktop:

  1. Fork on github.com first.
  2. File > Clone Repository > select your fork from the GitHub.com tab.

GitHub CLI (one command):

gh repo fork Community-Access/accessibility-agents --clone
cd accessibility-agents

For this workshop, you will fork the Community-Access/accessibility-agents repository.

On GitHub.com

  1. Go to github.com/Community-Access/accessibility-agents.
  2. Find the Fork button in the upper-right area of the page.
    • Screen reader users (NVDA/JAWS): Press B to cycle through buttons. The Fork button is near the top of the page, after the Watch and Star buttons.
    • VoiceOver users: Use VO+U to open the Buttons rotor and navigate to "Fork."
  3. GitHub shows a "Create a new fork" page. The defaults are correct:
    • Owner: your username
    • Repository name: accessibility-agents
    • Copy the main branch only: checked (leave this checked)
  4. Activate Create fork.
  5. GitHub redirects you to your fork: github.com/your-username/accessibility-agents.

You now have your own copy. The original repository at Community-Access/accessibility-agents is untouched.

Using GitHub CLI

gh repo fork Community-Access/accessibility-agents --clone=false

This creates the fork on GitHub without cloning it locally. We will clone in the next step.

4. Step 2: Clone Your Fork Locally

Now download your fork to your computer so you can work on it.

Using VS Code

  1. Open VS Code.
  2. Open the command palette: Ctrl+Shift+P (or Cmd+Shift+P).
  3. Type "Git: Clone" and press Enter.
  4. Paste your fork URL: https://github.com/your-username/accessibility-agents.git (replace your-username with your GitHub username).
  5. Choose a folder (for example, Documents) and confirm.
  6. When the clone finishes, VS Code offers to open the repository. Accept.

Using the terminal

git clone https://github.com/your-username/accessibility-agents.git
cd accessibility-agents

Using GitHub Desktop

  1. Open GitHub Desktop.
  2. Go to File, then Clone repository.
  3. Select the GitHub.com tab and find your-username/accessibility-agents.
  4. Choose a local path and click Clone.

Using GitHub CLI

gh repo clone your-username/accessibility-agents
cd accessibility-agents

After cloning, your local repository has one remote called origin that points to your fork.

Learning Cards: Cloning Your Fork

Screen reader users
  • Use Ctrl+Shift+P then "Git: Clone" and paste your fork URL -- VS Code announces progress and opens the repository when done
  • After cloning, press Ctrl+Shift+E to open the Explorer and verify the file tree loaded correctly
  • Run git remote -v in the terminal (Ctrl+\``) to confirmorigin` points to your fork URL
Low vision users
  • After cloning, the Explorer sidebar populates with the repository files -- increase sidebar width by dragging its edge for better readability
  • The VS Code title bar shows the repository folder name, confirming which project is open
  • Use Ctrl+P to quick-open any file by name if the file tree is hard to navigate at high zoom
Sighted users
  • After cloning, the Explorer sidebar shows the full file tree; the title bar displays the folder name
  • Look for the blue "Open Folder" notification or the repository name in the bottom Status Bar to confirm the clone succeeded
  • The Source Control panel (Ctrl+Shift+G) should show the repository with main as the current branch

5. Step 3: Add the Upstream Remote

See also: Appendix E: Advanced Git for advanced remote and upstream management.

Your clone knows about your fork (origin). It does not know about the original repository. You need to add it as a second remote called upstream.

Why this matters

Without the upstream remote, you cannot:

  • Pull new changes that other contributors make to the original repository
  • Keep your fork up to date
  • Verify your changes work with the latest code

Add the upstream remote

git remote add upstream https://github.com/Community-Access/accessibility-agents.git

Verify your remotes

git remote -v

You should see:

origin    https://github.com/your-username/accessibility-agents.git (fetch)
origin    https://github.com/your-username/accessibility-agents.git (push)
upstream  https://github.com/Community-Access/accessibility-agents.git (fetch)
upstream  https://github.com/Community-Access/accessibility-agents.git (push)

Two remotes: origin (your fork) and upstream (the original).

In VS Code: You can also add the remote using the command palette. Press Ctrl+Shift+P, type "Git: Add Remote," enter upstream as the name, and paste the upstream URL.

6. Step 4: Create a Feature Branch

Never work directly on the main branch of your fork. Always create a feature branch for each change. This keeps main clean and in sync with the upstream.

Create and switch to a new branch

git checkout -b agents/your-username-my-agent

The branch name agents/your-username-my-agent follows the workshop convention for Day 2 capstone branches. Replace your-username with your GitHub username and my-agent with a short name for your agent.

In VS Code

  1. Click the branch name in the bottom-left status bar (or press Ctrl+Shift+P and type "Git: Create Branch").
  2. Type the branch name: agents/your-username-my-agent.
  3. Press Enter. VS Code creates the branch and switches to it.

In GitHub Desktop

  1. Click the Current Branch dropdown.
  2. Click New Branch.
  3. Type the branch name and click Create Branch.

Verify you are on the new branch

git branch

The current branch has an asterisk (*) next to it.

7. Step 5: Make Your Changes

Now you are on your feature branch and ready to work. For the capstone, you will create an agent file. For other contributions, you might edit documentation, fix a bug, or add a feature.

General principles for contributing

  • Keep changes focused. One branch, one purpose. If you want to make two unrelated changes, use two branches and two pull requests.
  • Follow the project's conventions. Look at existing files for patterns in naming, formatting, and structure.
  • Write meaningful commit messages. Describe what you changed and why. "Fix typo in README" is clear. "Update files" is not.

Stage and commit your changes

After editing:

git add your-file.md
git commit -m "Add my-agent accessibility agent"

Or stage all changed files:

git add .
git commit -m "Add my-agent accessibility agent"

In VS Code

  1. Open the Source Control panel: Ctrl+Shift+G (or Cmd+Shift+G).
  2. Changed files appear under "Changes." Click the + icon next to each file to stage it, or click + on the "Changes" header to stage all.
    • Screen reader users: Navigate to the Source Control view. Each changed file is listed. Press Enter on a file to see the diff. Use the inline actions to stage.
  3. Type your commit message in the text field at the top.
  4. Press Ctrl+Enter (or Cmd+Enter) to commit.

Multiple commits are fine

You do not need to make all your changes in a single commit. In fact, smaller commits are better because they are easier to review and easier to revert if something goes wrong.

8. Step 6: Push to Your Fork

Your commits are saved locally. Now push them to your fork on GitHub.

First push (new branch)

git push -u origin agents/your-username-my-agent

The -u flag sets up tracking so future pushes from this branch go to the right place automatically.

Subsequent pushes

git push

In VS Code

After committing, the Source Control panel shows a Sync Changes button (or a cloud icon with an up arrow). Click it to push.

Alternatively, use the command palette: Ctrl+Shift+P, type "Git: Push."

In GitHub Desktop

After committing, click the Push origin button in the top bar.

Verify on GitHub

After pushing, visit your fork on GitHub: github.com/your-username/accessibility-agents. You should see a banner saying "your-username-my-agent had recent pushes" with a Compare and pull request button.

9. Step 7: Open a Pull Request

A pull request asks the upstream maintainers to merge your branch into their repository.

From the GitHub.com banner

  1. After pushing, GitHub shows a yellow banner on your fork with a Compare and pull request button. Click it.
  2. GitHub opens the "Open a pull request" page. Verify:
    • Base repository: Community-Access/accessibility-agents
    • Base branch: main
    • Head repository: your-username/accessibility-agents
    • Compare branch: agents/your-username-my-agent
  3. Write a descriptive title. Example: "Add document-contrast-checker agent."
  4. In the body, explain:
    • What your change does
    • Why it is useful
    • Any testing you did
    • Reference any related issues with Closes #XX if applicable
  5. If the project has a PR template, fill in all the required sections.
  6. Activate Create pull request.

From the Pull Requests tab

  1. Go to the upstream repository: github.com/Community-Access/accessibility-agents.
  2. Click the Pull requests tab.
  3. Click New pull request.
  4. Click compare across forks.
  5. Set the head repository to your fork and the compare branch to your feature branch.
  6. Click Create pull request and fill in the details.

Using GitHub CLI

gh pr create --repo Community-Access/accessibility-agents --title "Add document-contrast-checker agent" --body "Description of what the agent does and why it is useful."

Screen reader tip: The PR creation form is a standard web form. Navigate with Tab to move between fields. The title field and body field are <input> and <textarea> elements. The base and compare dropdowns use ARIA listbox patterns.

Learning Cards: Opening a Pull Request

Screen reader users
  • The PR form has a title input and a body textarea -- Tab between them; your screen reader announces field labels
  • The base and compare branch dropdowns use ARIA listbox patterns -- press Down Arrow to open and select branches
  • After submitting, GitHub navigates to the new PR page; press h to jump by headings and find the "Files changed" section
Low vision users
  • The "Compare and pull request" yellow banner appears at the top of your fork page after pushing -- it is a large, visible button
  • Use browser zoom (Ctrl+=) to enlarge the PR creation form if the text inputs are too small
  • The base and head repository/branch selectors appear near the top of the form -- verify these before submitting
Sighted users
  • After pushing, look for the yellow "Compare and pull request" banner at the top of your fork's GitHub page
  • Verify the base repository and branch (upstream/main) and head repository (your fork) are correct in the dropdown selectors
  • The PR creation form preview tab shows how your Markdown description will render -- check it before submitting

10. Step 8: Respond to Review Feedback

After you open a pull request, maintainers and peers will review your changes. They may:

  • Approve - your PR is ready to merge
  • Request changes - you need to update your PR
  • Comment - ask questions or suggest improvements without formally requesting changes

How to respond to requested changes

  1. Read each review comment carefully. Understand what the reviewer is asking.
  2. Make the requested changes in your local clone.
  3. Stage, commit, and push:
git add modified-file.md
git commit -m "Address review feedback: improve guardrails section"
git push
  1. Your new commits automatically appear in the open pull request. The reviewer is notified.
  2. Reply to each review comment explaining what you changed, or ask clarifying questions if the feedback is unclear.

Review etiquette

  • Thank the reviewer. They spent time reading your code.
  • Address every comment. Even if you disagree, explain your reasoning.
  • Do not take feedback personally. Review is about the code, not about you.
  • Ask questions. If you do not understand a comment, ask. Reviewers expect questions from new contributors.

The Day 1 connection: You practiced code review in Chapter 15. The same principles apply here, but now you are on the other side -- receiving feedback instead of giving it.

11. Keeping Your Fork in Sync

Over time, other people's changes get merged into the upstream repository. Your fork does not update automatically. You need to sync it.

Sync from the command line

# Make sure you are on main
git checkout main

# Download the latest changes from upstream
git fetch upstream

# Merge upstream changes into your local main
git merge upstream/main

# Push the updated main to your fork
git push origin main

Sync from GitHub.com

  1. Go to your fork on GitHub.
  2. If your fork is behind the upstream, GitHub shows a banner: "This branch is X commits behind Community-Access:main."
  3. Click Sync fork, then Update branch.

Sync from GitHub CLI

gh repo sync your-username/accessibility-agents

When to sync

  • Before starting new work: Always sync before creating a new feature branch. This ensures your branch starts from the latest code.
  • Before opening a PR: Sync and merge main into your feature branch to check for conflicts before asking for review.
  • Periodically: If you are working on a long-running branch, sync weekly to avoid large conflicts.

Learning Cards: Keeping Your Fork in Sync

Screen reader users
  • Run git fetch upstream then git merge upstream/main in the terminal -- listen for "Already up to date" or a merge summary announcing new commits
  • Use git status after syncing to confirm your local main is not behind the upstream
  • On GitHub.com, the "Sync fork" button is near the top of your fork page; press Tab to reach it and Enter to activate
Low vision users
  • On GitHub.com, the "Sync fork" button appears below the repository description with a dropdown showing how many commits behind you are
  • After syncing, the Status Bar in VS Code shows no up/down arrows next to the branch name, confirming you are in sync
  • If a merge conflict occurs during sync, VS Code highlights conflicts with colored backgrounds (green = yours, blue = upstream)
Sighted users
  • On GitHub.com, look for the "Sync fork" button below the green Code button -- it shows "N commits behind" if your fork is out of date
  • Click "Update branch" in the dropdown to sync your fork with one click
  • In VS Code, the sync icon (circular arrows) next to the branch name in the Status Bar performs fetch + merge in one action

12. The Fork Workflow Checklist

Use this checklist every time you contribute to a repository you do not own:

  • Fork the repository on GitHub
  • Clone your fork locally
  • Add the upstream remote (git remote add upstream URL)
  • Create a feature branch (git checkout -b branch-name)
  • Make your changes, stage, and commit
  • Push your branch to your fork (git push -u origin branch-name)
  • Open a pull request from your fork to the upstream
  • Respond to review feedback with additional commits
  • After merge, sync your fork (git fetch upstream && git merge upstream/main)
  • Delete the feature branch (locally and on your fork)

Cleaning up after merge

After your PR is merged, delete the feature branch:

# Delete the local branch
git checkout main
git branch -d agents/your-username-my-agent

# Delete the remote branch on your fork
git push origin --delete agents/your-username-my-agent

GitHub also offers a "Delete branch" button on the merged PR page.

13. If You Get Stuck

Problem What to do
Fork button is grayed out You may not be signed in. Sign in to GitHub.com first.
Clone fails with permission error Make sure you are cloning your fork (your-username/repo), not the upstream. You do not have write access to the upstream.
git remote -v shows only origin Run git remote add upstream URL from Section 5.
Push fails with "permission denied" You are probably trying to push to the upstream instead of your fork. Check git remote -v and push to origin.
PR shows conflicts with main Sync your fork (Section 11), merge main into your branch, resolve conflicts, push again.
Reviewer requested changes but I do not understand Reply to the review comment with a question. Reviewers expect questions from new contributors.
"Repository not found" when cloning Double-check the URL. Make sure the fork exists under your account.
Accidentally committed to main instead of a branch Check Appendix E for how to move commits to a new branch.
I finished but I am not sure I did it right Compare your work against the Challenge 15 reference solution (for agent discovery) or the Challenge 16 reference solution (for the capstone). Your version does not need to match exactly.

Next: Chapter 19: Accessibility Agents
Back: Chapter 17: Issue Templates
Related appendices: Appendix E: Advanced Git | Appendix O: Branch Protection

Authoritative Sources

Use these official references when you need the current source of truth for facts in this chapter.

Section-Level Source Map

Use this map to verify facts for each major section in this file.