GIT Going with GitHub

Day 2 Chapter Episode 47 12-15 min

Fork and Contribute

The complete fork-based open source contribution workflow from fork to upstream pull request.

Workshop docs

fork and contribute

Listen

Download MP3 Subscribe via RSS

Transcript

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.

Alex: Yes. The original project is usually called the upstream repository. Your fork stays connected to that upstream, and that connection is what lets you propose your changes back with a pull request.

Jamie: That also explains the Day 1 difference. In the Learning Room repository, each learner had their own provisioned repo and could make the issue, branch, commit, pull request, and merge directly there.

Alex: Right. In open source, you usually do not get write access to the upstream repository. So the pattern becomes fork first, branch on your fork, and ask maintainers to review the change before it lands.

Jamie: I want to slow down on three words that sound similar when you're new: fork, clone, and branch. They all make copies, kind of, but not in the same way.

Alex: Good place to pause. A fork lives on GitHub under your account, and it copies the whole repository. A clone lives on your computer, and it gives you a local working copy. A branch lives inside a repository, local or remote, and it isolates one line of work.

Jamie: So if I say, I cloned the upstream, that means something different from, I forked the upstream.

Alex: Very different. If you clone the upstream directly, you can read and edit locally, but you probably cannot push changes back there. If you fork first and then clone your fork, your local copy is connected to a GitHub repo where you do have permission to push.

Jamie: Can you describe the flow without relying on the visual diagram?

Alex: Picture three places from left to right. On the left is the upstream repository on GitHub. In the middle is your fork on GitHub. On the right is your computer. The fork action copies left to middle, cloning copies middle to right, pushing sends your committed work from right to middle, and the pull request proposes moving the change from middle back to left.

Jamie: That makes the direction much clearer. Edit locally, push to my fork, request review from upstream.

Alex: And there are a few practical checks that help you stay oriented. If you use a screen reader, `git remote -v` will read out the remotes, and the VS Code Status Bar can announce the current branch after you move focus there with F6. You can also use `Ctrl+Shift+P`, then Git: Checkout to, to hear branch names in the picker.

Jamie: For low vision users, the URL is a helpful clue too. A fork URL includes your username, like `github.com/your-name/repo`, while the upstream URL includes the project owner's name.

Alex: Yes, and in VS Code the branch name in the lower-left Status Bar is worth checking often. If it's small, zooming with `Ctrl+=` can make that status information easier to read.

Alex: When you're ready to fork, start on GitHub.com at the repository you want to contribute to. For a workshop practice repository, that may be `Community-Access/accessibility-agents`, which is part of the living Accessibility Agents catalog.

Jamie: And to be careful with current challenge rules: Challenge 15 is browse-first. Learners are not required to fork the Accessibility Agents repository just to complete that discovery challenge.

Alex: Correct. Forking becomes important when you're practicing this contribution workflow, or when your chosen Challenge 16 Capstone Project repository accepts pull requests. On the repository page, find the Fork button near the top of the page.

Jamie: If I'm using NVDA or JAWS, I can press B to move through buttons, and the Fork button is usually near Watch and Star. With VoiceOver, the Buttons rotor can help me jump to Fork.

Alex: After you activate Fork, GitHub opens a Create a new fork page. The usual defaults are right: the owner is your username, the repository name stays the same, and Copy the main branch only stays checked. Then activate Create fork.

Jamie: And after that, GitHub sends me to my copy, with my username in the URL.

Alex: Exactly. If you prefer GitHub CLI, you can create the fork without cloning by running `gh repo fork OWNER/REPO --clone=false`. Replace `OWNER/REPO` with the actual upstream repository name.

Jamie: Now the fork exists on GitHub, but I still need the files on my computer.

Alex: Right. Clone your fork, not the upstream, unless you have a very specific reason. In VS Code, open the command palette with `Ctrl+Shift+P`, or `Cmd+Shift+P` on macOS, run Git: Clone, paste your fork URL, choose a local folder, and open the repository when VS Code offers.

Jamie: So the URL should include my username, not the upstream owner's username.

Alex: Yes. In the terminal, the command is `git clone https://github.com/your-username/repo-name.git`, then `cd repo-name`. Replace the username and repository name with the real ones.

Jamie: What about GitHub Desktop and the GitHub CLI?

Alex: In GitHub Desktop, use File, Clone repository, choose the GitHub.com tab, select your fork, pick a local path, and clone it. With GitHub CLI, run `gh repo clone your-username/repo-name`, then change into the folder.

Jamie: After cloning, what remotes do I have?

Alex: At first, usually just one: `origin`. In this workflow, `origin` should point to your fork. That name matters because later, when you push, you want your work going to the repo you control.

Alex: Now add the upstream remote. This is the connection from your local clone back to the original project.

Jamie: So `origin` is my fork, and `upstream` is the original repository. That's the naming convention.

Alex: Exactly. From inside the local repository, run `git remote add upstream https://github.com/OWNER/REPO.git`, using the upstream repository's URL. Then run `git remote -v` to verify both remotes.

Jamie: What should I hear or see when I verify?

Alex: You should see `origin` listed with your username in the URL, for fetch and push. You should also see `upstream` listed with the original owner's URL. If both point to the same place, stop and fix that before continuing.

Jamie: A common mistake would be cloning the upstream, then trying to push and getting a permission error.

Alex: Exactly. Another common one is setting `origin` to the upstream by accident. If a push says permission denied, don't assume Git is broken. First check `git remote -v` and confirm where your push is trying to go.

Jamie: We have the remotes. Now we need a branch, right?

Alex: Yes. Create a feature branch for the specific change you're making. In the terminal, `git switch -c fix-typo-in-readme` creates the branch and moves you onto it.

Jamie: And the branch name should describe the change, not just be something like `stuff`.

Alex: Please, yes. In VS Code, you can use the branch name in the Status Bar or the command palette to create and switch branches. In GitHub Desktop, use the Current Branch control, create a new branch, and make sure it's based on `main` unless the project tells you otherwise.

Jamie: How do I verify I didn't stay on `main` by accident?

Alex: In the terminal, run `git branch` or `git status`; Git will tell you the current branch. In VS Code, check the lower-left branch name. In GitHub Desktop, check the Current Branch field before editing.

Alex: Now make the change. Keep it focused, follow the project's contributing guidance, and avoid mixing unrelated fixes in one pull request.

Jamie: That sounds especially important in accessibility work. A maintainer should be able to understand what barrier changed, what file changed, and how to review it.

Alex: Exactly. After editing, stage and commit your work. In the terminal, `git status` shows changed files, `git add filename` stages one file, and `git commit -m "Clear summary of the change"` records the commit.

Jamie: And in VS Code, the Source Control panel gives me the changed files, lets me stage them, enter a message, and commit.

Alex: Right. Multiple commits are okay while you're working. Maintainers may later ask you to squash or clean them up, but early on, the most important thing is making clear, reviewable commits.

Jamie: So I don't need to panic if my branch has three small commits instead of one perfect commit.

Alex: No panic. Clear history helps, but a pull request can still be reviewed while it has multiple commits.

Alex: Next, push your branch to your fork. The first push usually uses `git push -u origin your-branch-name`.

Jamie: What does the `-u` part do?

Alex: It sets an upstream tracking relationship for that branch, so future pushes and pulls know which remote branch to use. After that first push, `git push` is usually enough from the same branch.

Jamie: In VS Code, this is where I might hear Publish Branch or Sync Changes.

Alex: Yes. In GitHub Desktop, use Push origin. Either way, remember that `origin` should be your fork. Then open GitHub.com and verify that the branch exists on your fork, often with a recently pushed branch banner near the top.

Jamie: That banner is a nice confirmation: my local commit made it to GitHub, but only to my fork so far.

Alex: Exactly. Nothing has changed upstream yet.

Jamie: Now comes the pull request, which is the part people worry about.

Alex: A pull request is a request for maintainers to review and possibly merge your branch into the upstream repository. If GitHub shows a Compare and pull request banner on your fork, activate it.

Jamie: And I need to check the base and compare settings, because they determine the direction.

Alex: Yes. The base repository should be the upstream project, usually on `main`. The compare side should be your fork and your feature branch. If those are reversed, the pull request will not say what you intend.

Jamie: If the banner isn't there, I can use the Pull requests tab and choose New pull request.

Alex: Right. You can also use GitHub CLI with `gh pr create`, then follow the prompts for base, head, title, and body. However you open it, write a clear title, summarize what changed, and include how you tested it or what you checked.

Jamie: That body is not just paperwork. It's how the reviewer knows where to focus.

Alex: Exactly. If your change is a draft, say so. A review-ready draft or a detailed contribution plan can still be valid evidence in the Capstone Project when that matches the challenge expectations.

Alex: Once the pull request is open, maintainers may comment, ask questions, or request changes.

Jamie: If they request changes, do I open a new pull request?

Alex: Usually no. Make the edits on the same local branch, commit them, and push to `origin` again. The pull request updates automatically because it is watching that branch.

Jamie: And review etiquette matters here.

Alex: It does. Reply to comments when you've addressed them, ask if something is unclear, and don't treat requested changes as rejection. Review is part of collaboration.

Jamie: I like that framing. The maintainer is helping the change fit the project, not grading your worth as a contributor.

Alex: Exactly. Keep the conversation specific, kind, and tied to the work.

Jamie: Forks can drift over time, though. The upstream project keeps changing while my fork sits there.

Alex: That's why you sync your fork. From the command line, first switch to your local `main` with `git switch main`. Then download the latest upstream changes with `git fetch upstream`.

Jamie: After fetching, those changes are available locally, but not merged yet.

Alex: Right. Merge them with `git merge upstream/main`. Then push the updated `main` back to your fork with `git push origin main`.

Jamie: So the full rhythm is local `main`, fetch upstream, merge upstream main, push origin main.

Alex: Yes. On GitHub.com, many forks also show a Sync fork button, which can update your fork from the upstream when there are no complicated conflicts. With GitHub CLI, `gh repo sync your-username/repo-name -b main` can do the same kind of update.

Jamie: When should I sync?

Alex: Before starting a new branch, after being away from a project for a while, and when a pull request says your branch is behind the base branch. If there are conflicts, slow down and resolve them carefully, or ask for help in the pull request.

Jamie: And if I'm already working on a feature branch, I may need to bring updated `main` into that branch too.

Alex: Right. That can be a merge or a rebase depending on the project's guidance. When you're new, follow the repository's instructions and ask before rewriting shared history.

Alex: Here's the whole loop in plain language: fork the upstream, clone your fork, add upstream, create a feature branch, make a focused change, commit it, push to your fork, and open a pull request upstream.

Jamie: Then respond to review, keep the fork synced, and after the pull request is merged, clean up the branch.

Alex: Yes. Locally, switch away from the feature branch, then delete it with `git branch -d your-branch-name`. On your fork, delete the remote branch with `git push origin --delete your-branch-name`, or use the delete button GitHub offers after merge.

Jamie: What are the stuck points people should recognize quickly?

Alex: Permission denied usually means you're pushing to a repo you don't control, or your authentication needs attention. Repository not found often means the URL is wrong or the fork doesn't exist under your account. A pull request with no changes usually means the base and compare settings are wrong, or you pushed a different branch than the one you selected.

Jamie: And if I accidentally committed to `main` instead of a feature branch?

Alex: Don't keep piling on work. Stop, make a new branch from the commit, and use the advanced Git guidance if you need to move commits or reset `main`. If you're unsure, ask before force pushing.

Jamie: For current details, use official GitHub documentation, the GitHub change log, and the project's own contributing file, because screens and buttons can change.

Alex: Exactly. And for the curriculum path, completing Challenge 15 unlocks Challenge 16, the Capstone Project, plus Bonus Challenges A through E. Those bonuses are a structured unlock path, and the capstone can involve Accessibility Agents, GLOW, or another meaningful repository.

Jamie: So this workflow is not just a Git exercise. It's the contribution shape you'll use when a real project asks for work through forks and pull requests.

Alex: That's it. Once you can identify upstream, origin, branch, push target, and pull request direction, the workflow becomes much less mysterious.

Workshop Content

Full chapter content from the Git Going with GitHub workshop guide.

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.