# Working with Pull Requests > > **Listen to Episode 6:** [Working with Pull Requests](https://lp.csedesigns.com/ggg/PODCASTS.html) - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. > **Related appendices:** [Appendix C: Markdown Reference](appendix-c-markdown-reference.md) | [Appendix B: Screen Reader Cheat Sheet](appendix-b-screen-reader-cheatsheet.md) > **Authoritative sources:** [GitHub Docs: About pull requests](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) | [GitHub Accessibility Guide: Pull Requests](https://accessibility.github.com/documentation/guide/pull-requests/) | [GitHub Accessibility Lab: CLI Guide](https://accessibility.github.com/documentation/guide/cli/) ## Creating, Reviewing, and Merging Pull Requests with a Screen Reader > **See also:** [Chapter 15: Code Review](15-code-review.md) covers the full review workflow including multi-file diffs and suggested changes. > Pull requests are where your work becomes a contribution. This guide takes you through the full pull request workflow - from opening one to participating in review - using only your keyboard and screen reader. > > **Official GitHub Accessibility Guide:** GitHub publishes an NVDA-focused guide for working with pull requests using a screen reader at [Using GitHub Pull Requests with a Screen Reader](https://accessibility.github.com/documentation/guide/pull-requests/). This chapter covers the same material with additional perspectives (VoiceOver, low vision, CLI) and workshop-specific challenges. Use the official guide as a companion reference. > > **Screen reader note - New Files Changed Experience:** This guide uses GitHub's improved Files Changed experience, which adds proper ARIA landmark structure to the Files Changed tab, including the file tree and diff navigation. This feature may already be active for your account - it has been broadly rolled out and may no longer appear as a Feature Preview toggle at all. > > **To verify:** Activate the **User Menu** button (top-right of any GitHub page) → activate **"Feature preview"** → scan the list for **"New Files Changed Experience"**: > > - If listed and the toggle announces **"Pressed"** (or **"Disable"**) - already enabled, no action needed > - If listed but **not Pressed** (or **"Enable"**) - activate the toggle to enable it > - If not listed at all - the feature has graduated to the standard interface; it is active automatically > > Full step-by-step instructions with per-screen-reader commands are in [Pre-Workshop Setup, Step 4](00-pre-workshop-setup.md#step-4---check-github-feature-preview-settings). > > **Browse vs Focus Mode (NVDA):** Use **Browse Mode** (the default) for reading PR conversations, navigating headings, and reviewing diffs. Switch to **Focus Mode** (`NVDA+Space`) only when you need to type in comment boxes or search fields. Switch back to Browse Mode to resume navigation. Maximize your browser window for consistent landmark layout. ## Workshop Recommendation (Chapter 6) Chapter 6 is the first **PR-validated chapter** where students convert issue work into merge-ready contributions. - **Challenge count:** 3 - **Time per challenge:** under 10 minutes each - **Evidence:** PR metadata, bot checks, and merged issue linkage - **Pattern:** small change -> linked PR -> green checks ### Chapter 6 Challenge Set 1. **Create one small branch change** - edit a practice file on a new branch. 2. **Open a linked PR** - use the PR template and include `Closes #XX`. 3. **Pass required checks** - respond to bot feedback until all required checks pass. ### CLI getting-started principles for pull request work For reliable PR workflows in the terminal: 1. Check current branch before pushing (`git branch --show-current`). 2. Keep PR scope small (one focused change per branch). 3. Confirm issue linkage in plain text (`Closes #`). 4. Validate check status after each push (`gh pr checks`). 5. Prefer documented command options only (`gh pr --help`). > **Branch guidance for Chapter 6:** This is the first chapter where you edit files and create branches. Use one of these two paths: > > - **Web editor (recommended for beginners):** When you edit a file on GitHub.com and click "Propose changes," GitHub creates a branch for you automatically. Name it `fix/yourname-issueXX` (for example, `fix/maria-issue42`). > - **Local Git (if you cloned in Block 0):** Create a feature branch with `git checkout -b fix/yourname-issueXX` from `main`. See the "Local Git Alternative" section below for the full command sequence. > > **Do not reuse your `learn/` branch for this short exercise unless your facilitator tells you to.** Chapter 6 works best with a short-lived feature branch such as `fix/yourname-issueXX`, because it teaches the pull request loop without mixing multiple challenges on one branch. ### Challenge 6.1 Step-by-Step: Create One Small Branch Change **Goal:** Edit one of the practice files and save your change on a new branch. **Where you are working:** your Learning Room repository on GitHub.com, using the web editor. **Before you start:** Open your **assigned Chapter 6.1 challenge issue** (the one titled "Chapter 6.1: Create One Small Branch Change (@yourname)"). The issue description tells you which file to edit and what to fix. The Learning Room has three practice files with intentional problems. Your assigned issue points you to one of them: The following table summarizes the practice files in the learning-room, what each file contains, and the type of issues to look for. | File | What it contains | What to fix | |------|-----------------|-------------| | `docs/welcome.md` | Introduction to open source contribution | Three `[TODO]` sections where content is missing | | `docs/keyboard-shortcuts.md` | Screen reader shortcut reference tables | Intentional errors in shortcut references | | `docs/setup-guide.md` | Getting-started instructions | Broken links and incomplete steps | **Steps using the web editor:** 1. In your Learning Room repository, navigate to the file specified in your issue. Use the file tree or the "Go to file" button (`T` keyboard shortcut). 2. Open the file and activate the **pencil icon** (Edit this file) button. - Screen reader users (NVDA/JAWS): Press `B` to navigate buttons, find "Edit this file," and press `Enter`. - VoiceOver users: Press `VO+U`, open Buttons rotor, find "Edit this file," and press `VO+Space`. 3. The file opens in the web editor. Make your change. For example: - If your issue is about a `[TODO]` section: replace the `[TODO]` placeholder with the requested content (one to three sentences). - If your issue is about a broken link: find and correct the URL. - If your issue is about a shortcut error: find and fix the incorrect value in the table. 4. Keep your change small and focused. Edit only what the issue asks for. **Proposing your changes (this creates your branch):** 1. After editing, activate the **Commit changes** button (green button above the editor). 2. A dialog appears. In the **Branch name** field, type: `fix/yourname-issueXX` (replace `yourname` with your GitHub username, and `XX` with the issue number). 3. Select **Create a new branch for this commit and start a pull request**. 4. Activate **Propose changes**. **You are done when:** GitHub shows the "Open a pull request" page. Your file change is saved on a new branch. Continue to Challenge 6.2. ### Challenge 6.2 Step-by-Step: Open a Linked PR **Goal:** Open a pull request > **Agentic strategy:** AI agents do not just deploy code directly; they submit pull requests. Learning to edit a file, format it in Markdown, and review a PR today prepares you to audit and approve AI-generated changes tomorrow. Make your Markdown clean and structured, and include the `Closes #XX` line that links to your challenge issue so it closes automatically on merge. **Where you are working:** the "Open a pull request" page that appeared after Challenge 6.1 (or navigate to Pull Requests tab and select "Compare and pull request"). 1. In the **Title** field, write a short description of your change. Examples: - "Complete the Who Can Contribute section in welcome.md" - "Fix broken accessibility settings link in setup-guide.md" - "Correct NVDA modifier key in keyboard-shortcuts.md" 2. In the **Body** field, use the PR template if one is provided. Make sure to include: - A summary of what you changed and why (at least 50 characters). - The line `Closes #XX` where `XX` is the number of your **assigned Chapter 6 challenge issue**. 3. Verify the **base branch** is `main` and the **compare branch** is your `fix/yourname-issueXX` branch. 4. Activate the **Create pull request** button. **You are done when:** Your PR appears in the Pull Requests list. The bot will begin running checks within about 30 seconds. Continue to Challenge 6.3. ### Challenge 6.3 Step-by-Step: Pass Required Checks **Goal:** Read bot feedback, fix any issues it finds, and get all required checks to pass. **Where you are working:** the Conversation tab of your open pull request. 1. Wait approximately 30 seconds after opening the PR. The bot posts a validation comment. 2. Read the bot comment carefully. It checks: - That your PR references an issue with `Closes #XX`. - That your PR description is detailed enough (50+ characters). - That your changed files are in the `learning-room/` folder. - Accessibility checks: heading hierarchy, descriptive link text, valid alt text. 3. If the bot reports failures: - Open the changed file from the **Files changed** tab. - Activate the pencil icon to edit the file again (directly on your branch). - Fix the issue the bot identified. - Commit the fix to the **same branch** (the bot re-runs automatically on each push). 4. Repeat step 3 until all required checks show a green checkmark. 5. When all checks pass, request a review from a peer or the facilitator. **You are done when:** The bot comment shows all required checks passed (green checkmarks). Your PR is ready for human review and merge. ### Expected Outcomes - Student opens a focused PR that maps to one issue. - Student uses `Closes #XX` correctly. - Student can interpret bot feedback and improve the PR. ### If You Get Stuck 1. Confirm your PR includes `Closes #XX` in title or body. 2. Check that changed files are only in `learning-room/`. 3. Open the bot validation comment and resolve one required check at a time. 4. If checks still fail, ask for peer or facilitator review with the exact error message. 5. Finished but not sure you did it right? Compare your work against the [Challenge 6 reference solution](solutions/solution-06-first-pr.md). ### Learning Moment A great PR is small, linked to an issue, and easy to review. Faster feedback builds confidence and momentum. ### Why this feels achievable - Scope is intentionally small. - Feedback is immediate and specific. - Success is visible (green checks + closed issue). ### About Learning Cards in This Chapter This chapter provides learning cards: expandable blocks that offer perspective-specific guidance for different ways of working. Not every card appears at every step. Open the ones that match how you work. The following table describes the six learning card types used in this chapter. | Card | Who it helps | What it covers | | --- | --- | --- | | Visual / mouse | Sighted users navigating with a mouse or trackpad | Click targets, visual cues, layout orientation | | Low vision | Users with magnification, zoom, or high-contrast themes | Zoom-friendly navigation, finding controls at high magnification, high contrast visibility | | NVDA / JAWS (Windows) | Screen reader users on Windows | Keystroke sequences, Focus and Browse mode, landmark paths | | VoiceOver (macOS) | Screen reader users on macOS | VO key sequences, rotor usage, interaction model | | GitHub.com web | All users working in the browser | Browser-based workflows without local tools | | CLI (git / gh) | Terminal users on any platform | Git and GitHub CLI commands for PR management | ## Local Git Alternative: The Full Branch-Edit-PR Workflow
If you cloned the learning-room in Block 0 and prefer working locally The web editor workflow (pencil button, "Propose changes") is the primary path taught in this chapter. If you cloned the Learning Room in Block 0 and are comfortable in a terminal, here is the local equivalent. This is the same workflow covered in depth in [Chapter 11: Git and Source Control](14-git-in-practice.md). **Step 1 - Sync and create a feature branch:** ```bash cd ~/Documents/learning-room git checkout main git pull origin main git checkout -b fix/welcome-todos ``` **Step 2 - Edit the file in your editor:** Open the file in VS Code or your preferred editor: ```bash code docs/welcome.md ``` Make your changes and save the file. **Step 3 - Stage, commit, and push:** ```bash git add docs/welcome.md git commit -m "Complete TODO sections in welcome.md" git push -u origin fix/welcome-todos ``` **Step 4 - Open a pull request:** ```bash gh pr create --title "Complete TODO sections in welcome.md" \ --body "Closes #42" --base main ``` Or open interactively: ```bash gh pr create ``` The GitHub CLI walks you through title, body, base branch, and reviewers. **What happens next is identical:** the Learning Room bot validates your PR, posts feedback, and you request a human reviewer - the same as the web workflow. > **Tip:** You can also create a named feature branch with `git checkout -b fix/yourname-issueXX` if you prefer that naming convention over the practice branch.
## What Is a Pull Request? A pull request (PR) is a proposal to merge changes from one branch into another. When you have: - Edited a file directly on GitHub (web editor) - Made changes in your fork - Made changes on a feature branch ...you open a PR to request that those changes be merged into the target branch (usually `main`). A PR shows: - **What** changed - a diff of every file - **Why** it changed - your PR description - **Conversation** - comments, reviews, and discussion - **Status** - automated checks (CI/CD) and review status > **Learning Room connection:** In the Learning Room repository, every hands-on contribution follows this pattern. For example, when you complete Challenge 3 (filling the `[TODO]` sections in `docs/welcome.md`), you open a PR that shows your added content as green `+` lines in the diff, your description explains which TODOs you completed and why, and the validation bot posts automated check results. The scenarios in this chapter use Learning Room files so you can follow along with real content. ## Navigating to Pull Requests > **Global pull requests dashboard:** GitHub now shows a global pull requests page at [github.com/pulls](https://github.com/pulls) listing all open PRs across every repository you have access to. This is now the **default landing page** when you click "Pull requests" in the top navigation bar (the one above the repository content, not inside a repository). You can opt out in your GitHub settings if you prefer the old behavior. Screen reader path: top navigation region > "Pull requests" link > Enter (or navigate to github.com/pulls directly).
Visual / mouse users Click the **Pull requests** tab in the repository navigation bar. The tab shows the count of open PRs. Click any PR title to open it.
Low vision users (zoom, high contrast) The **Pull requests** tab is in the repository navigation bar near the top of the page. At 200% browser zoom or higher, the tab bar may wrap to a second line. The tab text includes the open PR count in parentheses. - In **Windows High Contrast** mode, the active tab is indicated by a system-colored underline, not just a color change. - At high magnification, use `Tab` to move through the repository navigation links if the tab bar is hard to target with a pointer. - Once in the PR list, PR titles are links with standard hover underlines. They remain clickable at any zoom level.
Screen reader users (NVDA / JAWS - Windows) 1. `D` → "Repository navigation" landmark 2. `K` to navigate tabs → "Pull requests, [N] open" 3. `Enter` to open
Screen reader users (VoiceOver - macOS) 1. `VO+U` → Landmarks → navigate to "Repository navigation" 2. Quick Nav `K` or `VO+Right` to navigate tabs → "Pull requests" 3. `VO+Space` to open
### From a PR notification If you received a notification about a PR, follow the notification link directly to the PR page.
GitHub CLI (gh) alternative List and view pull requests from your terminal: ```bash # List open PRs gh pr list # Filter by review status gh pr list --search "review-requested:@me" # View a specific PR in the terminal gh pr view 42 # Open a PR in your browser gh pr view 42 --web ``` **Setup:** Install the GitHub CLI from [cli.github.com](https://cli.github.com) and authenticate with `gh auth login`. See [Appendix D](appendix-d-git-authentication.md) for details.
### Learning Cards: Navigating to Pull Requests **Screen reader users:** - Press `D` to jump to the "Repository navigation" landmark, then `K` to reach the "Pull requests" tab link -- this is faster than arrowing through the entire page - The tab link announces the open PR count ("Pull requests, 7 open"), giving you a quick triage number without opening the list - From any GitHub page, press `G` then `P` (two sequential key presses in Focus Mode) to jump directly to the repository's Pull Requests tab - Use terminal-first triage when needed: `gh pr list` then `gh pr view ` to review essentials before entering the web diff **Low-vision users:** - The Pull requests tab is in the repository navigation bar near the page top; at 200%+ zoom the tab bar may wrap to a second line, but each tab remains a distinct clickable link - The open PR count appears in parentheses next to the tab text; zoom into the tab area to read it without opening the list - Use `Tab` key navigation to step through the repository nav links if pointer targeting is difficult at high magnification **Sighted users:** - Click the **Pull requests** tab in the horizontal navigation bar below the repository name; the badge shows the number of open PRs - Bookmark the URL pattern `github.com/OWNER/REPO/pulls` to skip navigation entirely - The active tab is underlined; open PRs are the default view -- use the "Closed" filter link to toggle ## The Pull Request List Page The PR list works identically to the Issues list: - `3` to navigate PR titles (they are h3 headings) - `I` to navigate list items - `F` or `E` / `Shift+E` to reach the search/filter field - Filters work the same as Issues: `is:open`, `author:@me`, `review-requested:@me`, etc. > **Screen reader note - PR list semantics:** The PR list does **not** have individual ARIA item containers with per-item semantics. To read a PR's full detail (title, author, labels, status), you must navigate sequentially with `Tab` or arrow keys through the elements for each item. Starting from a PR title link, `Tab` forward to find the author, labels, and review status for that same PR before moving to the next title. > > **Hovercards:** Hovercards appear when you hover over usernames and links in the PR list, adding extra verbosity. To reduce this noise: go to your GitHub Profile → Accessibility settings → disable "Show link previews" and similar hover triggers. This makes sequential navigation significantly less cluttered. ## Anatomy of a Pull Request Page A PR page has three main tabs: ```text [PR title - h1] [State badge: Open / Merged / Closed / Draft] [Author, base ← compare, timestamp] [ Conversation ] [ Commits ] [ Files changed ] ↑ tab bar landmark ─── Conversation Tab ──────────────────────────────────────── [PR description - authored by opener] [Status checks summary] [Activity / review thread] [Review comment - h3] [Line comments - nested] [Merge controls (for maintainers)] [Comment box] ─── Commits Tab ───────────────────────────────────────────── [List of commits, grouped by date - h3 for dates] [Each commit as a list item with SHA, message, author] ─── Files Changed Tab ──────────────────────────────────────── [File filter search] [File tree (left panel)] [Diff for each file - each file is a heading] [Line-level comment threads within diffs] ``` ## Navigating the PR Tab Bar The Conversation, Commits, and Files changed tabs are in a “Pull request navigation tabs” landmark.
Visual / mouse users The three tabs - **Conversation**, **Commits**, and **Files changed** - appear just below the PR title. Click the tab you want. The active tab is underlined. The count on **Files changed** shows how many files were modified.
Low vision users (zoom, high contrast) The PR tab bar sits just below the PR title and state badge. At high zoom levels: - The three tabs (**Conversation**, **Commits**, **Files changed**) may stack or wrap. Each tab remains a distinct clickable link. - The active tab is distinguished by an underline. In Windows High Contrast mode, the underline uses a system accent color for visibility. - The **Files changed** tab includes a count (for example, "Files changed 3"). This count is part of the link text, not a separate element. - If the tabs are hard to click at high magnification, use `Tab` key navigation from the PR title area to reach each tab link sequentially.
Screen reader users (NVDA / JAWS) 1. Press `D` → navigate to “Pull request navigation tabs” 2. Press `←` or `→` arrow keys to move between tab options 3. Press `Enter` to activate a tab
Screen reader users (VoiceOver) 1. `VO+U` → Landmarks → “Pull request navigation tabs” 2. `VO+Right` to move between tabs 3. `VO+Space` to activate
Each tab link reads with its name and the count: "Files changed, 3 files changed." ## Reading the Conversation Tab ### PR Description 1. `2` → navigate to "Description" h2 heading 2. `↓` to read the description 3. Markdown renders as semantic HTML - headings, lists, code blocks are fully accessible ### Status Checks Section Below the description, the status checks summary shows whether automated tests passed. Look for: - “All checks have passed” / “Some checks failed” / “Checks pending” - A “Show all checks” button or link
Visual / mouse users Status checks appear as a coloured banner below the PR description - green tick for passed, red X for failed, yellow spinner for running. Click **Show all checks** to expand the full list. Click a check name to go to its run log.
Screen reader users (NVDA / JAWS - Windows) 1. Press `H` or `2` to find the "Checks" or "Status checks" heading 2. Press `K` to navigate links for individual check names 3. Press `Enter` on a check to see its details
Screen reader users (VoiceOver - macOS) 1. Quick Nav `H` or `VO+Cmd+H` to jump to the "Checks" or "Status checks" heading 2. Quick Nav `K` to navigate check name links 3. `VO+Space` on a check to see its details
See [GitHub Actions & Workflows](appendix-q-actions-workflows.md) for full guidance on reading status checks. ### Review Comments Each review comment thread is an h3. Navigate with `3`: - Hear the reviewer's username, timestamp, and their review verdict ("approved" or "requested changes") - Then the body of their review comment - Then any replies to that comment To reply to a review comment: ```text Step 1: Navigate to the comment (3) Step 2: Tab to "Reply…" link/button Step 3: The reply text area appears - Focus Mode → type your reply Step 4: Ctrl+Enter to submit ``` #### Resolving conversations When a review comment has been addressed, you can mark the conversation as resolved: 1. Navigate to the conversation thread (`3` to jump between comment headings) 2. `Tab` to the end of the thread to find the **"Resolve conversation"** button 3. Press `Enter` to mark it resolved 4. The conversation collapses and shows as "Resolved" Resolved conversations are still accessible - they collapse but can be expanded again. This helps both reviewers and authors track which feedback items have been addressed. ### Learning Cards: Reading the Conversation Tab
Screen reader users - Press `2` to jump between H2 headings: "Description" (the PR body) and "Activity" (the comment thread) - Press `3` to jump between individual review comments (each is an H3); each announces the reviewer's username, timestamp, and verdict - Press `D` to jump to the "Add a comment" landmark at the bottom to skip directly to the reply box
Low vision users - Status checks below the description show green checkmarks (passed), red X marks (failed), or yellow spinners (running); zoom in on this area after opening a PR - Review comments have a colored left border: green for "Approved," red for "Request changes," grey for "Comment" - The merge button section at the bottom turns green when all checks pass; it is disabled (greyed out) when checks are pending or reviews are missing
Sighted users - The Conversation tab has a timeline layout: PR description at the top, status checks below, then comments and events in chronological order - Review verdicts appear as banners in the timeline: a green banner for Approve, a red banner for Request Changes - The merge section at the bottom shows which requirements are met (green checkmarks) and which are pending (yellow dots)
## Reading the Commits Tab ```text Step 1: Navigate to Commits tab (D → PR tabs → Enter) Step 2: 3 to navigate date group headings ("Commits on April 20") Step 3: I to navigate individual commits within a date group Step 4: Each commit: SHA link, message, author, [Verified] badge if signed Step 5: Enter on a commit to open its diff ``` ## Reading the Checks Tab The Checks tab shows the status of automated tests, CI workflows, and other verification processes running on your PR. It helps you verify whether your changes pass all required tests before merging.
Screen reader users (NVDA / JAWS - Windows) 1. Navigate to the **"Pull request tabs"** landmark (`D`) 2. Navigate between tab links (`K` or `Tab`) and activate "Checks" 3. Press `D` to jump to the **"check suites"** section - this moves focus to the collapsed details button of the first check 4. Press `B` or `Tab` to navigate between check buttons; each button is labeled with the check's name 5. Press `Enter` or `Space` to expand a check and reveal its logs: - Navigate through the check steps with `K` or `Tab` - Activate a step for more details 6. For a summary view: press `D` to navigate to the **"check run summary"** section
Screen reader users (VoiceOver - macOS) 1. `VO+U` -> Landmarks -> "Pull request tabs" -> activate "Checks" 2. `VO+U` -> Landmarks -> navigate to "check suites" section 3. `VO+Right` to move through check buttons, `VO+Space` to expand 4. For summary: `VO+U` -> Landmarks -> "check run summary"
### Learning Cards: Reading the Checks Tab **Screen reader users:** - Each check button is labeled with the check's name and its pass/fail state; listen for "success" or "failure" in the ARIA label before expanding the details - Press `D` to jump between the "check suites" and "check run summary" landmarks to get a high-level pass/fail overview without expanding every check - If a check fails, expand it and press `K` to navigate step links inside the log -- the failing step is usually labeled with a red X icon described in the accessible name **Low-vision users:** - Passed checks show a green checkmark icon; failed checks show a red X icon; pending checks show a yellow dot -- in Windows High Contrast mode these map to system success/error/warning colors - At high zoom, each check row may wrap; the icon and check name stay on the first line, while the duration and "Details" link may appear on a second line - Click the "Details" link next to a failed check to jump to the CI log; failed steps are highlighted with a red background that remains visible in high-contrast themes **Sighted users:** - Scan the Checks tab for a row of green checkmarks (all passed) or spot a red X (failed); the summary banner at the top reads "All checks have passed" or "Some checks were not successful" - Click any check name to expand its step log inline; failed steps are bolded and marked with a red X so you can skip passing steps quickly - The "Re-run" button (circular arrow) appears next to each check for maintainers; use it to retry a flaky check without pushing a new commit ## Reading the Files Changed Tab This is the core of a code review. You will read diffs - the before/after state of every file that changed. > **Note:** This guide uses GitHub's improved Files Changed experience. If your Files Changed tab doesn't match these steps, refer to the screen reader verification steps in the prerequisite callout at the top of this chapter - the feature may need to be enabled in Feature Preview, or it may already be active for your account with no action required. ### File Tree (left panel) The file tree lists every changed file. Use it to jump directly to a specific file’s diff.
Visual / mouse users The file tree panel is on the left side of the Files Changed tab. It lists every modified file. Click a filename to scroll the diff view to that file. You can collapse or expand folders by clicking the arrow. Type in the filter box at the top to narrow the file list.
Low vision users (zoom, high contrast) The file tree panel is on the left side of the Files Changed tab. At 200% zoom or higher: - The panel may collapse into a toggle button or hamburger menu. Look for a sidebar toggle icon in the top-left area of the Files Changed tab. - File names in the tree may be truncated. Hover over a truncated name to see the full path in a tooltip. - The filter box at the top of the file tree lets you type a filename to narrow the list. This is faster than scrolling through a long file list at high magnification. - Each file entry shows an icon indicating the change type (added, modified, deleted). In high-contrast themes, these icons use distinct system colors rather than relying on green/red alone.
Screen reader users (NVDA / JAWS - Windows) 1. `D` → navigate to "File tree" region 2. `↑/↓` to navigate the file list 3. `Enter` to jump to that file's diff
Screen reader users (VoiceOver - macOS) 1. `VO+U` → Landmarks → navigate to "File tree" region 2. `VO+Down` to move through the file list 3. `VO+Space` to jump to that file's diff
### The Diff for a File Each changed file has: - A **file heading** (its path, e.g., "src/index.html") - navigable with `3` or `H` - A **stats line** ("24 additions, 6 deletions") - The **diff content** - a table where each row is one line of code #### Lines in a diff are read as - `+ Added line` - line that was added - `- Removed line` - line that was removed - `Context line` - unchanged line shown for context ### Navigating the diff with a screen reader
Visual / mouse users Each file’s diff shows added lines in green and removed lines in red. Scroll the page to read through changes. Unchanged context lines are shown in white/grey. Collapse a file’s diff by clicking the arrow next to its filename heading. Use `Ctrl+F` (browser Find) to search for specific text within visible diffs.
Low vision users (zoom, high contrast) The diff view uses color-coded backgrounds: green for added lines, red for removed lines, and white or grey for unchanged context. **Tips for reading diffs at high magnification:** - Enable **Split diff** view (dropdown at the top of Files Changed tab) to see old and new versions side-by-side. At very high zoom, **Unified diff** may be more comfortable because it uses a single column. - Each line has a `+` or `-` prefix in addition to the color. In Windows High Contrast mode, the color backgrounds are replaced with system contrast colors and the `+`/`-` prefixes remain visible. - Use `Ctrl+F` (browser Find) to search for specific text within the visible diffs. This is often faster than scrolling through long diffs at high zoom. - Line numbers appear on the left margin. At extreme zoom levels, these may overlap the code text. Hover over a line number to see the full number in a tooltip. - To collapse a long diff and reduce visual clutter, click the arrow next to the file heading.
Screen reader users (NVDA / JAWS) 1. `T` to jump to the next diff table 2. Switch to Focus Mode: `Insert+Space` (NVDA) or `Insert+Z` (JAWS) 3. `Ctrl+Alt+↓` to move down one row (next diff line), `Ctrl+Alt+↑` to move up 4. `Ctrl+Alt+→` to read across columns (line number | change type | content) 5. The screen reader reads: “+ Add accessible name to submit button” 6. Collapsed sections contain unchanged code. Focus the expand/disclosure control and activate it (`Enter` or `Space`) to reveal the hidden lines. > **Tip:** You can also use `↓` and `↑` in Focus Mode for simpler line-by-line reading when you don’t need column-level detail. Use `NVDA+F7` to get a headings overview of all changed files before diving into individual diffs.
Screen reader users (VoiceOver) 1. `T` or `VO+U` → Tables → select the diff table 2. `VO+Shift+Down` to enter the table 3. `VO+Right/Left` for columns, `VO+Up/Down` for rows
### Placing an inline comment on a diff line
Visual / mouse users Hover over any line in the diff - a blue `+` button appears on the left margin. Click it to open a comment box for that line. Type your comment, then click **Add single comment** (posts immediately) or **Start a review** (batches the comment with others). To select a range of lines, click and drag across the line numbers on the left.
Low vision users (zoom, high contrast) The inline comment button (a blue `+` icon) appears on hover near the left margin of each diff line. At high magnification: - The `+` button can be small and hard to target. **Keyboard alternative:** `Tab` into the diff line area, then press `Enter` on the focused line to open the comment box. - Once the comment box opens, it spans the full width of the diff area. At 200% zoom, you may need to scroll down to see the **Add single comment** and **Start a review** buttons below the text area. - In Windows High Contrast mode, the `+` button uses the system link color rather than blue, and the comment box border uses the system window frame color.
Screen reader users (NVDA / JAWS - Windows) 1. Navigate to the specific line in the diff (using the table navigation above) 2. While focused on that line, a comment button appears - press `Enter` or `Space` to activate it 3. A comment box opens below the line 4. Focus Mode → type your comment 5. `Tab` to **Add single comment** button (instant comment) OR **Start a review** (to batch comments) #### Multi-line comment (Windows) 1. Focus the first line you want to comment on 2. Press `Shift+↓` to extend the selection to additional lines 3. A comment button appears - activate it 4. The comment applies to the full range of selected lines
Screen reader users (VoiceOver - macOS) 1. Navigate to the specific line in the diff (using the table navigation above) 2. While focused on that line, `VO+Space` on the comment button that appears 3. A comment box opens below the line 4. `VO+Shift+Down` to interact with the text area, then type your comment 5. `VO+Shift+Up` to stop interacting, then `Tab` to **Add single comment** and `VO+Space` #### Multi-line comment (macOS) 1. Focus the first line and `Shift+↓` to extend the selection 2. `VO+Space` on the comment button that appears 3. The comment applies to the full range of selected lines
### Viewing comments within the diff Inline comments appear as expandable threads within the diff table. Navigate to them with `3` (they are h3 headings). Each thread shows the comment, any replies, and a "Reply" button. ### Learning Cards: Reading the Files Changed Tab
Screen reader users - Press `D` to jump to the "File tree" landmark on the left; use `Up/Down Arrow` to navigate files, `Enter` to jump to that file's diff - Press `T` to jump to the next diff table; use `Ctrl+Alt+Down Arrow` to walk through diff lines row by row - Each line is announced with its change type: `+` for additions, `-` for deletions, and context lines with no prefix
Low vision users - Added lines have a green background; removed lines have a red background; in high-contrast themes, these use bolder system-color shading - Toggle between Split diff (two-column) and Unified diff (single-column) using the dropdown at the top of the Files Changed tab; Unified is easier at high zoom - Each file heading shows the path and a summary like "+24 -6"; zoom in on this to quickly assess the scope of changes per file
Sighted users - The file tree panel on the left lists every changed file; click a filename to scroll the right panel to that file's diff - Green-highlighted lines are additions; red-highlighted lines are deletions; grey lines are unchanged context - Hover over any line number in the diff to reveal a blue "+" button for adding an inline review comment
## Opening a Pull Request ### Tool Cards: Open a Pull Request **github.com (browser):** 1. Push your branch, then click the **Compare & pull request** banner (or go to **Pull requests > New pull request**). 2. Set base branch to `main`, compare branch to yours. 3. Fill in the title and description, then click **Create pull request**. **github.dev (web editor):** 1. After committing changes, click the **Source Control** icon. 2. Click **Create Pull Request** in the Source Control panel header. 3. Fill in details and submit. **VS Code Desktop (GitHub Pull Requests extension):** 1. Press `Ctrl+Shift+P`, type **GitHub Pull Requests: Create Pull Request**. 2. Select base and compare branches. 3. Fill in the title and description, then click **Create**. **GitHub Desktop:** 1. After pushing your branch, click **Create Pull Request** in the banner or **Branch > Create Pull Request**. 2. This opens github.com with the PR form pre-filled. **Git CLI / GitHub CLI:** ```bash git push -u origin your-branch gh pr create --title "Your title" --body "Description" ``` ### From the web editor workflow (editing a file on GitHub) 1. You edited a file → GitHub showed a "Propose changes" form 2. You named your branch and activated "Propose changes" 3. GitHub redirected you to the "Open a pull request" page ### From a fork or feature branch
Visual / mouse users 1. Navigate to the repository on GitHub 2. If you recently pushed, a yellow banner “Compare & pull request” appears at the top - click it 3. If no banner appears: click the **Pull requests** tab → click the green **New pull request** button 4. Use the branch dropdowns to choose your **base** branch (what to merge into) and your **compare** branch (your changes) 5. Click **Create pull request**
Screen reader users (NVDA / JAWS - Windows) 1. Navigate to the repository 2. A "Compare & pull request" banner may appear (if you recently pushed) - activate it 3. OR: Navigate to Pull Requests tab → "New pull request" 4. Choose your base branch (what to merge into) and compare branch (your changes)
Screen reader users (VoiceOver - macOS) 1. Navigate to the repository 2. Check for a "Compare & pull request" banner - Quick Nav `B` to find and `VO+Space` to activate it 3. OR: navigate to Pull Requests tab (`VO+U` → Landmarks → Repository navigation) → Quick Nav `B` for "New pull request" 4. Use the branch dropdowns (`VO+Space` to open, arrow keys to select) to choose base and compare branches
### Filling out the PR form #### Title field ```text Step 1: F to navigate to the title field Step 2: Focus Mode → type a descriptive title Step 3: Good: "Add keyboard navigation for carousel component" Step 4: Bad: "Fix bugs" ``` #### Description field ```text Step 1: Tab to the body text area Step 2: Focus Mode → type using the PR template (if provided) ``` > **Copilot can write your PR description:** If your account has Copilot access, a **"Copilot actions"** button appears in the description toolbar. Activate it to open a menu with options to generate a summary of your changes or an outline of the most important changes in the PR. Screen reader users: `Tab` from the description text area to find the "Copilot actions" button, then press `Enter` to open the menu and `↑/↓` to choose an option. If no template, use this structure: ```markdown ## Summary What does this PR change and why? ## Changes - Added `aria-label` to the search button - Fixed keyboard trap in the modal dialog - Replaced `
` with `