+No open PR to review? The steps below assume a pull request with a diff. If your Learning Room has no open PR (or the peer simulation PR is already merged), review the sample file at
+docs/code-review-sample.mdinstead: read the whole file, find at least two issues (typos, headings, formatting, alt text, clarity), and post your review - one thing done well, at least one constructive suggestion, and a one-sentence verdict - as a comment on your Challenge 12 issue. A plain file has no diff, so there is no Files changed tab and no inline comment button; the issue comment is where your review lives. See the Challenge 12 issue template for the full Path B steps.
Goal: Navigate a PR diff using screen reader-friendly tools and post 2-3 specific, constructive inline comments.
Where you are working: GitHub.com (Files changed tab of a PR) or VS Code with the GitHub Pull Requests extension.
diff --git a/html/docs/CHALLENGES.html b/html/docs/CHALLENGES.html index 7a55ce61..5fb45b79 100644 --- a/html/docs/CHALLENGES.html +++ b/html/docs/CHALLENGES.html @@ -366,6 +366,7 @@Evidence to post: Share the merged PR link and the issue number that closed.
+Before you close the issue, answer the four Confidence Check reflection questions from Chapter 10 in a comment on your Challenge 9 issue. There are no wrong answers - this is for you.
Before moving on, scan the Challenge 9 solution reference to make sure you caught both the merge and verification steps.
diff --git a/html/search-index.json b/html/search-index.json index 2ce1b9b7..219e0bd9 100644 --- a/html/search-index.json +++ b/html/search-index.json @@ -413,12 +413,6 @@ "url": "docs/course-guide.html", "body": "Course Guide Listen to Episode 0: Welcome to Git Going with GitHub - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. GitHub Learning Room - Your Complete Workshop Companion Welcome. You are about to begin a two-day journey into open source collaboration using GitHub, VS Code, and GitHub Copilot - all designed for screen reader and keyboard-only navigation. This guide is your starting point and table of contents for everything in this workshop. Note: Workshop content is being actively refined for the May 2026 cohort. Students should expect updates to materials leading up to and during the course. Important: tools and websites change. GitHub.com, VS Code, GitHub Copilot, github.dev, browser extensions, and agent experiences are living products. We do our best to keep this curriculum current and source-backed, but labels, page order, shortcuts, preview features, model availability, and account-policy behavior can shift. If the documentation and your screen differ, use the exploration pattern taught in Chapters 2 and 3: orient by URL, page title, H1, landmarks, tab names, button labels, keyboard help, and the VS Code Command Palette. Then report the mismatch so the documentation can be corrected. How This Course Works This is a two-day workshop built around one idea: you will make real contributions to a real open source project. Not simulated. Not pretend. Real. Live Agenda and Self-Paced Curriculum The live hackathon agenda is intentionally smaller than the full curriculum. Live sessions prioritize the core contribution path, while the complete chapter set remains available for self-paced preparation, catch-up, remote participation, and post-event continuation. Live core: The facilitator chooses the minimum path needed for participants to make and understand a real contribution. Async follow-up: Chapters and challenges not covered live can be completed after the session using the Learning Room, solutions, podcasts, and Slack channel. Remote participation: Remote cohorts should use the same checkpoints and evidence prompts, with written instructions available before each live block. The Two Days Day 1 - GitHub Foundations (Browser) You learn GitHub's web interface using only your keyboard and screen reader. The live Day 1 core path gets you through repository navigation, issues, branches, commits, and a first pull request. Review practice, merge conflicts, labels, notifications, and culture exercises remain available as stretch or async follow-up. Day 2 - VS Code + Accessibility Agents (Desktop) You move to Visual Studio Code, learn GitHub Copilot, and activate the Accessibility Agents ecosystem. The live Day 2 core path prepares you to make a real contribution, and the async continuation path gives you time to polish and submit it well. The Journey Arc Day 1 - Learn the skill in the browser Navigate → Issue → Pull Request → Review → Merge ↓ (bridge: press . on any GitHub repo - VS Code opens in your browser) github.dev - VS Code on the web, no install needed Same keyboard shortcuts · Same screen reader mode · Edit files · Open PRs Limits: no local terminal or debugger, only web-compatible extensions, and not the full desktop agent workflow ↓ (you've earned the desktop - now it makes sense) Day 2 - Deepen with VS Code + Accessibility Agents VS Code basics → Copilot inline → Copilot Chat @daily-briefing → @issue-tracker → @pr-review → @analytics → prepare upstream The key principle: Learn the manual skill first, then see how it is automated. The agents only make sense when you already understand what they are doing. Before You Begin Start with Get Going with GitHub if you want the most guided path. It explains how GitHub Classroom creates your private Learning Room repository, how Challenge 1 appears, how evidence prompts work, and how to choose between browser, github.dev, VS Code, GitHub Desktop, and command-line paths. Complete everything in Chapter 00: Pre-Workshop Setup before Day 1. This chapter walks you through: Creating a GitHub account Installing Git Setting up VS Code (optional for Day 1, required for Day 2) Configuring your screen reader for GitHub Verifying everything works Time needed: About 30 minutes. Companion Audio Series Every chapter and appendix has a companion podcast episode - a conversational two-host overview that previews or reviews the key concepts. Listen before reading a chapter to know what to expect, or after to reinforce what you learned. Browse the podcast episodes with HTML5 audio players Subscribe via RSS in your preferred podcast app Episodes are 8-18 minutes each - perfect for commutes, walks, or screen reader breaks Day 1: GitHub Foundations These chapters are designed to be read and practiced in order. Each builds on the one before it. # Chapter What You Will Learn Time Start Get Going with GitHub GitHub Classroom onboarding, Learning Room first steps, support, and tool choice " }, - { - "id": "docs/CHALLENGES.html", - "title": "Challenge Hub", - "url": "docs/CHALLENGES.html", - "body": "Challenge Hub Welcome to the Challenge Hub - your guide to all 16 core challenges and 5 bonus challenges. The challenges are the practice path for the course. Each one asks you to do a small piece of real GitHub work, leave evidence of what you did, and then close the issue so the next challenge can open. The goal is not speed. The goal is to build a contributor rhythm you can trust: orient yourself, make the move, verify the result, and ask for help with clear facts when something feels off. Prefer the exact issue-style flow? Open the consolidated issue walkthrough: Issue-Style Challenge Walkthrough . How Challenges Work Start in your private Learning Room repository, not in the public curriculum repository. Open the Issues tab, find the challenge issue assigned to you, and read the issue body before acting. Each issue explains the task, the evidence prompt, and any buddy check or automated check that applies. When a challenge asks for evidence, post it as a comment on that challenge issue. Evidence can be a link, a short reflection, the name of a branch, a pull request number, or a note about what you tried and what happened. After you post the evidence, close the challenge issue. The Student Progression Bot uses that closed issue as the signal to open the next challenge. Every challenge below includes a reference solution. Treat those files as worked examples, not answer keys. Your exact branch name, issue number, wording, or file count may differ. What matters is whether you practiced the skill and can explain the result. Day 1: You Belong Here (Challenges 1-9) Challenge 1: Find Your Way Around Chapters: Ch02-04 | Evidence: Comment This first challenge is about orientation. Before you edit anything, you learn how a repository is organized: where the Code tab lives, where Issues live, how the file tree behaves, and how the README gives a project its front door. What to do: Find the Code tab and count the files or folders in the repository root Open the Issues tab and identify at least one issue or confirm the tab exists Navigate to docs/welcome.md and read the opening paragraph Find the repository description and the rendered README Evidence to post: Describe what you found and name one navigation shortcut or screen reader technique that helped. Compare your result with the Challenge 1 solution reference when you want a second view of the same exploration path. Challenge 2: File Your First Issue Chapter: Ch05 | Evidence: Comment Issues are how maintainers turn observations into trackable work. In this challenge, you find a small TODO in the Learning Room and write an issue that another person could understand without being in the room with you. What to do: Open docs/welcome.md and search for TODO Create a new issue with a specific title Explain what needs to change, where it is, and why the change would help Evidence to post: Link to the issue you created and include one sentence about why your title is clear. If you want to compare tone and structure, read the Challenge 2 solution reference . Challenge 3: Join the Conversation Chapter: Ch05 | Evidence: Comment Open source is conversation as much as code. This challenge teaches you how to participate in an issue thread with an @mention, a reaction, and a comment that moves the work forward. What to do: Find your buddy's Challenge 2 issue or a facilitator-provided peer simulation issue Leave a meaningful comment with an @mention Add a reaction to the original issue or a helpful comment Evidence to post: Link to your comment and describe what made it useful, kind, or specific. The Challenge 3 solution reference shows one way to make a short comment feel genuinely collaborative. Challenge 4: Branch Out Chapter: Ch06 | Evidence: Comment A branch is a safe workspace. It lets you try a change without rewriting the main version of the project. In this challenge, you create your own branch and confirm that you know where your work will happen. What to do: Find the branch selector on the Code tab Create a branch named learn/YOUR-USERNAME from main Confirm the branch selector now names your branch Evidence to post: Write the branch name you created and how you confirmed you were on it. Use the Challenge 4 solution reference if you want to check your branch mental model. Challenge 5: Make Your Mark Chapter: Ch06 | Evidence: Comment This is your first small content change. You edit a file, replace a TODO with real text, and commit the change with a message that explains what happened. What to do: Switch to your learn/YOUR-USERNAME branch Edit docs/welcome.md to replace the TODO with useful content Write a commit message that explains the change in plain language Evidence to post: Share your commit message and the file you edited. For a worked example of a focused commit, compare with the Challenge 5 solution reference . Challenge 6: Open Your First Pull Request Chapter: Ch06 | Evidence: Comment A pull request is the conversation around a proposed change. It lets" - }, { "id": "docs/11-vscode-interface.html", "title": "VS Code: Interface and Setup", @@ -455,12 +449,6 @@ "url": "docs/10-notifications-and-day-1-close.html", "body": "Notifications Listen to Episode 10: Notifications and Mentions - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. Related appendices: Appendix T: Community and Social | Appendix U: Discussions and Gists | Appendix V: GitHub Mobile Authoritative sources: GitHub Docs: About notifications Managing Your GitHub Notification Inbox See also: Appendix V: GitHub Mobile for managing notifications on your phone. GitHub notifications are how GitHub tells you when something needs your attention. This guide teaches you to keep the inbox useful - not overwhelming - using only your keyboard and screen reader. Workshop Recommendation (Chapter 10) Chapter 10 is a guided practice chapter with no required Day 1 challenge issue of its own. The walkthrough below corresponds to the optional Bonus D: Notification Mastery issue, which unlocks after Challenge 15 (Day 2). You can read this chapter and try the walkthrough today, but you do not need a challenge issue to do so, and you do not need to wait for Bonus D to unlock to practice it. Challenge count: 0 required (optional Bonus D covers this topic later) Automation check: none - notification settings are account-level and cannot be validated by the Learning Room PR bot Evidence: if you want credit now, note what you tried in a comment on your current challenge issue; formal evidence is submitted on the Bonus D issue once it unlocks Pattern: configure, filter, act Important Note: This Challenge Uses GitHub's Web Notification Inbox This challenge focuses on GitHub's web-based notification inbox (at github.com/notifications ), not email notifications. You do NOT need to configure email delivery, and you do NOT need to receive emails to complete this challenge. Why we focus on the web inbox: Email delivery depends on your mail server, ISP, spam filters, and account settings—factors outside our control GitHub's web notification inbox is always available and works the same way for everyone Professional developers typically check notifications in the GitHub app or web UI rather than waiting for emails The skills you learn (filtering, muting, managing noise) apply whether you eventually enable email or not What you will do: Use GitHub's web notification inbox to view and filter notifications Configure repository watch levels to control what notifications you receive Practice managing your inbox with GitHub's built-in actions (mute, mark done) If you have already configured email notifications on your GitHub account, that is fine—but this challenge does not require or test email delivery. Focus on the web inbox workflow instead. Chapter 10 Practice Set Configure notifications and practice inbox management - set your watch level, use filters to find relevant notifications, and perform one inbox action. (Formal evidence for this goes on the Bonus D issue once it unlocks.) Practice Step-by-Step: Notification Inbox Walkthrough Goal: Set up a useful notification workflow so you can keep up with reviews, mentions, and assignments without inbox overload. Where you are working: the GitHub.com notifications page and your Learning Room repository settings. Estimated time: 5-8 minutes. Open your Learning Room repository on GitHub.com. Find the Watch button near the top-right of the repository page (next to Star and Fork). Activate the Watch dropdown and select Participating and @mentions . This means you only get notified when someone @mentions you or you are directly participating in a thread. Open the notifications inbox by navigating to https://github.com/notifications (or activate the bell icon in the GitHub header). In the notification filters, activate the Review requested filter. This shows only notifications where someone has asked you to review their PR. Clear that filter and activate the Assigned filter. This shows notifications for issues and PRs assigned to you. Open one notification by activating its title link. Read it briefly, then navigate back to the inbox. Perform one inbox action on a non-critical notification thread: Press M to mute the thread (you will not receive future updates), or Press E to mark done (removes it from inbox but you can still get future updates). Screen reader tip: The notification list is a standard list of links. Each notification announces its title, repository, and reason (mention, review request, assignment). Use arrow keys to move between notifications and Enter to open one. You are done when: You have changed your watch level, used two different filters, and performed one inbox action (mute or done). Completing Chapter 10: Submit Your Evidence This practice does not have its own required issue. If you want to record what you tried, post a comment on your current challenge issue (or later on the Bonus D: Notification Mastery issue once it unlocks): Chapter 10 practice completed: - Watch level set to: Participating and @mentions - Filters tested: Re" }, - { - "id": "docs/15-code-review.html", - "title": "Code Review: PRs, Diffs, and Constructive Feedback", - "url": "docs/15-code-review.html", - "body": "Code Review: PRs, Diffs, and Constructive Feedback Related appendices: Appendix G: VS Code Reference | Appendix C: Markdown Reference Authoritative sources: GitHub Docs: Reviewing changes in pull requests | GitHub Accessibility Guide: Pull Request Reviews Day 2, Block 2 Material This chapter unifies PR management, accessible code review, and the reviewer's craft into one chapter. Part 1 covers the GitHub Pull Requests extension in VS Code. Part 2 covers accessible code review with diffs and inline comments. Part 3 adds the reviewer's judgment framework. Part 1: The GitHub Pull Requests Extension See also: Appendix G: VS Code Reference for the complete list of GitHub Pull Requests extension keyboard shortcuts. Listen to Episode 13: The GitHub Pull Requests Extension - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. Managing Pull Requests from VS Code Day 2, Block 2 Material This guide covers the GitHub Pull Requests and Issues extension: viewing open PRs, checking out PR branches for local testing, reviewing PRs with screen reader-accessible tools, creating PRs directly from VS Code, using PR templates, and syncing PR status with GitHub. Prerequisites: Working with Pull Requests , Git & Source Control in VS Code Mac keyboard shortcuts: Throughout this chapter, all Ctrl+ shortcuts use Cmd+ on Mac, and Alt+ shortcuts use Option+ on Mac. For example: Ctrl+Shift+P → Cmd+Shift+P , Ctrl+Shift+G → Cmd+Shift+G , Alt+F2 → Option+F2 . Context menus ( Shift+F10 on Windows) use Ctrl+Return on Mac. Workshop Recommendation (Chapter 15, Part 1) Chapter 15, Part 1 introduces the GitHub Pull Requests extension for managing PRs directly from VS Code. Challenge count: 2 guided challenges Automation check: none (extension installation and review state are account-local) Evidence: issue comment with confirmation of actions completed Pattern: install, check out, review, comment Chapter 15, Part 1 Practice Set Install the GitHub Pull Requests extension - add the extension to VS Code and sign in with your GitHub account. Check out a PR and post a review comment - download a PR branch locally, read the diff, and post one constructive review comment. Practice 15.1 Step-by-Step: Install the Extension Goal: Install the GitHub Pull Requests and Issues extension and authenticate with your GitHub account. Where you are working: VS Code desktop with your Learning Room repository open. Estimated time: 3-5 minutes. Open the Extensions sidebar: Ctrl+Shift+X (Mac: Cmd+Shift+X ). Your screen reader announces "Extensions: Marketplace." The search box has focus. Type GitHub Pull Requests in the search box and press Enter . Navigate down the results list. Select GitHub Pull Requests (publisher: GitHub). Activate the Install button. VS Code installs the extension and may show a notification. After installation, VS Code prompts you to sign in. Activate Sign in to GitHub . A browser window opens for GitHub OAuth. Approve the authorization and return to VS Code. Verify: open the Explorer sidebar ( Ctrl+Shift+E ). You should now see a GitHub section in the sidebar showing Pull Requests and Issues. Screen reader tip: After step 5, if the install notification disappears before you can read it, open Command Palette ( Ctrl+Shift+P ) and run Notifications: Focus Notification Toast . You are done when: The GitHub section appears in your Explorer sidebar and shows pull requests from your Learning Room repository. Practice 15.2 Step-by-Step: Check Out a PR and Post a Comment Goal: Check out someone else's PR branch locally, read the diff in VS Code, and post one constructive review comment. Where you are working: VS Code with the GitHub Pull Requests extension installed. Estimated time: 10-15 minutes. Open the Command Palette: Ctrl+Shift+P (Mac: Cmd+Shift+P ). Type GitHub Pull Requests: Focus on Pull Requests View and select it. The Pull Requests panel opens. Navigate the list of open PRs. Find one that is not yours (a classmate's PR from Chapter 6, 7, or 14). With the PR focused, press Enter or activate Checkout from the context menu ( Shift+F10 on Windows). VS Code switches to that PR's branch. Open the Command Palette again and run GitHub Pull Requests: Open Changed Files . This shows the list of files the PR changed. Open one changed file. VS Code opens the Diff Editor showing old content on the left and new content on the right. Navigate the diff with the Accessible Diff Viewer : press F7 to move to the next change, Shift+F7 for the previous change. Your screen reader announces each change (added lines, removed lines). Find one specific thing to comment on: a typo, an unclear sentence, a missing step, or something the author did well. To add an inline comment: position your cursor on the line you want to comment on, then open Command Palette and run GitHub Pull Requests: Add Comment . Type your constructive comment and activate Add Com" - }, { "id": "docs/04-the-learning-room.html", "title": "The Learning Room: Your Personal Practice Repository", @@ -485,6 +473,18 @@ "url": "docs/06-working-with-pull-requests.html", "body": "Working with Pull Requests Listen to Episode 6: Working with Pull Requests - 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 B: Screen Reader Cheat Sheet Authoritative sources: GitHub Docs: About pull requests | GitHub Accessibility Guide: Pull Requests | GitHub Accessibility Lab: CLI Guide Creating, Reviewing, and Merging Pull Requests with a Screen Reader See also: Chapter 15: Code Review 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 . 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 . 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 Create one small branch change - edit a practice file on a new branch. Open a linked PR - use the PR template and include Closes #XX . 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: Check current branch before pushing ( git branch --show-current ). Keep PR scope small (one focused change per branch). Confirm issue linkage in plain text ( Closes #<number> ). Validate check status after each push ( gh pr checks ). 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/<username> 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: This section is preparation for your Challenge 6: Open Your First PR issue - there is no separate issue for making the edit itself. Pick one of the three practice files below, make one focused change, and save it on a new branch. When your branch has a commit, come back and continue with the PR steps later in this chapter. The Learning Room has three practice files with intentional problems. Your assigned issue points you to one of them: The following table summarizes" }, + { + "id": "docs/15-code-review.html", + "title": "Code Review: PRs, Diffs, and Constructive Feedback", + "url": "docs/15-code-review.html", + "body": "Code Review: PRs, Diffs, and Constructive Feedback Related appendices: Appendix G: VS Code Reference | Appendix C: Markdown Reference Authoritative sources: GitHub Docs: Reviewing changes in pull requests | GitHub Accessibility Guide: Pull Request Reviews Day 2, Block 2 Material This chapter unifies PR management, accessible code review, and the reviewer's craft into one chapter. Part 1 covers the GitHub Pull Requests extension in VS Code. Part 2 covers accessible code review with diffs and inline comments. Part 3 adds the reviewer's judgment framework. Part 1: The GitHub Pull Requests Extension See also: Appendix G: VS Code Reference for the complete list of GitHub Pull Requests extension keyboard shortcuts. Listen to Episode 13: The GitHub Pull Requests Extension - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. Managing Pull Requests from VS Code Day 2, Block 2 Material This guide covers the GitHub Pull Requests and Issues extension: viewing open PRs, checking out PR branches for local testing, reviewing PRs with screen reader-accessible tools, creating PRs directly from VS Code, using PR templates, and syncing PR status with GitHub. Prerequisites: Working with Pull Requests , Git & Source Control in VS Code Mac keyboard shortcuts: Throughout this chapter, all Ctrl+ shortcuts use Cmd+ on Mac, and Alt+ shortcuts use Option+ on Mac. For example: Ctrl+Shift+P → Cmd+Shift+P , Ctrl+Shift+G → Cmd+Shift+G , Alt+F2 → Option+F2 . Context menus ( Shift+F10 on Windows) use Ctrl+Return on Mac. Workshop Recommendation (Chapter 15, Part 1) Chapter 15, Part 1 introduces the GitHub Pull Requests extension for managing PRs directly from VS Code. Challenge count: 2 guided challenges Automation check: none (extension installation and review state are account-local) Evidence: issue comment with confirmation of actions completed Pattern: install, check out, review, comment Chapter 15, Part 1 Practice Set Install the GitHub Pull Requests extension - add the extension to VS Code and sign in with your GitHub account. Check out a PR and post a review comment - download a PR branch locally, read the diff, and post one constructive review comment. Practice 15.1 Step-by-Step: Install the Extension Goal: Install the GitHub Pull Requests and Issues extension and authenticate with your GitHub account. Where you are working: VS Code desktop with your Learning Room repository open. Estimated time: 3-5 minutes. Open the Extensions sidebar: Ctrl+Shift+X (Mac: Cmd+Shift+X ). Your screen reader announces "Extensions: Marketplace." The search box has focus. Type GitHub Pull Requests in the search box and press Enter . Navigate down the results list. Select GitHub Pull Requests (publisher: GitHub). Activate the Install button. VS Code installs the extension and may show a notification. After installation, VS Code prompts you to sign in. Activate Sign in to GitHub . A browser window opens for GitHub OAuth. Approve the authorization and return to VS Code. Verify: open the Explorer sidebar ( Ctrl+Shift+E ). You should now see a GitHub section in the sidebar showing Pull Requests and Issues. Screen reader tip: After step 5, if the install notification disappears before you can read it, open Command Palette ( Ctrl+Shift+P ) and run Notifications: Focus Notification Toast . You are done when: The GitHub section appears in your Explorer sidebar and shows pull requests from your Learning Room repository. Practice 15.2 Step-by-Step: Check Out a PR and Post a Comment Goal: Check out someone else's PR branch locally, read the diff in VS Code, and post one constructive review comment. Where you are working: VS Code with the GitHub Pull Requests extension installed. Estimated time: 10-15 minutes. Open the Command Palette: Ctrl+Shift+P (Mac: Cmd+Shift+P ). Type GitHub Pull Requests: Focus on Pull Requests View and select it. The Pull Requests panel opens. Navigate the list of open PRs. Find one that is not yours (a classmate's PR from Chapter 6, 7, or 14). With the PR focused, press Enter or activate Checkout from the context menu ( Shift+F10 on Windows). VS Code switches to that PR's branch. Open the Command Palette again and run GitHub Pull Requests: Open Changed Files . This shows the list of files the PR changed. Open one changed file. VS Code opens the Diff Editor showing old content on the left and new content on the right. Navigate the diff with the Accessible Diff Viewer : press F7 to move to the next change, Shift+F7 for the previous change. Your screen reader announces each change (added lines, removed lines). Find one specific thing to comment on: a typo, an unclear sentence, a missing step, or something the author did well. To add an inline comment: position your cursor on the line you want to comment on, then open Command Palette and run GitHub Pull Requests: Add Comment . Type your constructive comment and activate Add Com" + }, + { + "id": "docs/CHALLENGES.html", + "title": "Challenge Hub", + "url": "docs/CHALLENGES.html", + "body": "Challenge Hub Welcome to the Challenge Hub - your guide to all 16 core challenges and 5 bonus challenges. The challenges are the practice path for the course. Each one asks you to do a small piece of real GitHub work, leave evidence of what you did, and then close the issue so the next challenge can open. The goal is not speed. The goal is to build a contributor rhythm you can trust: orient yourself, make the move, verify the result, and ask for help with clear facts when something feels off. Prefer the exact issue-style flow? Open the consolidated issue walkthrough: Issue-Style Challenge Walkthrough . How Challenges Work Start in your private Learning Room repository, not in the public curriculum repository. Open the Issues tab, find the challenge issue assigned to you, and read the issue body before acting. Each issue explains the task, the evidence prompt, and any buddy check or automated check that applies. When a challenge asks for evidence, post it as a comment on that challenge issue. Evidence can be a link, a short reflection, the name of a branch, a pull request number, or a note about what you tried and what happened. After you post the evidence, close the challenge issue. The Student Progression Bot uses that closed issue as the signal to open the next challenge. Every challenge below includes a reference solution. Treat those files as worked examples, not answer keys. Your exact branch name, issue number, wording, or file count may differ. What matters is whether you practiced the skill and can explain the result. Day 1: You Belong Here (Challenges 1-9) Challenge 1: Find Your Way Around Chapters: Ch02-04 | Evidence: Comment This first challenge is about orientation. Before you edit anything, you learn how a repository is organized: where the Code tab lives, where Issues live, how the file tree behaves, and how the README gives a project its front door. What to do: Find the Code tab and count the files or folders in the repository root Open the Issues tab and identify at least one issue or confirm the tab exists Navigate to docs/welcome.md and read the opening paragraph Find the repository description and the rendered README Evidence to post: Describe what you found and name one navigation shortcut or screen reader technique that helped. Compare your result with the Challenge 1 solution reference when you want a second view of the same exploration path. Challenge 2: File Your First Issue Chapter: Ch05 | Evidence: Comment Issues are how maintainers turn observations into trackable work. In this challenge, you find a small TODO in the Learning Room and write an issue that another person could understand without being in the room with you. What to do: Open docs/welcome.md and search for TODO Create a new issue with a specific title Explain what needs to change, where it is, and why the change would help Evidence to post: Link to the issue you created and include one sentence about why your title is clear. If you want to compare tone and structure, read the Challenge 2 solution reference . Challenge 3: Join the Conversation Chapter: Ch05 | Evidence: Comment Open source is conversation as much as code. This challenge teaches you how to participate in an issue thread with an @mention, a reaction, and a comment that moves the work forward. What to do: Find your buddy's Challenge 2 issue or a facilitator-provided peer simulation issue Leave a meaningful comment with an @mention Add a reaction to the original issue or a helpful comment Evidence to post: Link to your comment and describe what made it useful, kind, or specific. The Challenge 3 solution reference shows one way to make a short comment feel genuinely collaborative. Challenge 4: Branch Out Chapter: Ch06 | Evidence: Comment A branch is a safe workspace. It lets you try a change without rewriting the main version of the project. In this challenge, you create your own branch and confirm that you know where your work will happen. What to do: Find the branch selector on the Code tab Create a branch named learn/YOUR-USERNAME from main Confirm the branch selector now names your branch Evidence to post: Write the branch name you created and how you confirmed you were on it. Use the Challenge 4 solution reference if you want to check your branch mental model. Challenge 5: Make Your Mark Chapter: Ch06 | Evidence: Comment This is your first small content change. You edit a file, replace a TODO with real text, and commit the change with a message that explains what happened. What to do: Switch to your learn/YOUR-USERNAME branch Edit docs/welcome.md to replace the TODO with useful content Write a commit message that explains the change in plain language Evidence to post: Share your commit message and the file you edited. For a worked example of a focused commit, compare with the Challenge 5 solution reference . Challenge 6: Open Your First Pull Request Chapter: Ch06 | Evidence: Comment A pull request is the conversation around a proposed change. It lets" + }, { "id": "agents/image alt text agent/agents/image-alt-text.agent.html", "title": "image-alt-text.agent", diff --git a/html/work.html b/html/work.html index af3c3ff5..c3038c58 100644 --- a/html/work.html +++ b/html/work.html @@ -907,6 +907,17 @@Before you close this issue, take two minutes to answer these questions in a comment below. There are no wrong answers - this is for you. (These are the same questions in the Chapter 10 Confidence Check, surfaced here so you see them before closing.)
++Screen reader tip: Copy these questions into your comment and type your answers directly below each one. Use a blank line between each question-answer pair so the structure is clear when read back.
+
Your evidence (fill in when closing this issue):
My PR was merged: [link]
@@ -1179,16 +1190,21 @@ If you get stuck
Challenge 12: Review Like a Pro
Source template: challenge-12-review.yml
Chapter: Ch15: Code Review
-What you will do: Perform a thorough code review on a peer-simulation PR (or a buddy's PR). Use the sample file at docs/code-review-sample.md for your review if you do not have a real PR to review. Leave inline comments, make a suggestion, and submit a verdict.
+What you will do: Perform a thorough code review. If your Learning Room has an open pull request, review that (Path A). If it does not, review the sample file at docs/code-review-sample.md instead (Path B). Either way, you will leave specific feedback and a verdict.
Why this matters: Code review is how teams maintain quality and teach each other.
-Step-by-step review process
+Choose your path
+
+- Path A (preferred): There is an open PR in this repository to review. Use the PR workflow below.
+- Path B (fallback): There is no open PR, or the only PR is already merged. Review the sample file and post your review as a comment on this issue.
+
+Not sure where to look? The peer simulation PR lives in your own Learning Room repository (the one you are in right now), not in the main workshop repository. Open the Pull requests tab here. If the Peer Simulation: Improve contribution guidance PR is missing or already merged, use Path B.
+Path A: Review a pull request
Step 1: Find the PR to review
-- Go to the Pull requests tab in this repository
-- Look for the Peer Simulation: Improve contribution guidance PR
+- Go to the Pull requests tab in this repository
+- Look for the Peer Simulation: Improve contribution guidance PR, or a classmate's open PR
- Click to open it
- Alternatively, if your facilitator gave you buddy access, open your buddy's Day 2 PR
-- If you do not have a real PR to review, open and review the sample file at
docs/code-review-sample.md instead.
Step 2: Go to the Files changed tab
@@ -1232,14 +1248,29 @@ Step 3: Leave inline c
```text
6. Click **Submit review**
-#### Review checklist
+#### Path B: Review the sample file (when no open PR is available)
+
+A plain Markdown file has no diff, so there is no **Files changed** tab and no inline comment button. Instead, you will read the file, find the issues, and post your review as a comment on **this Challenge 12 issue**.
-When reviewing, ask yourself:
-- ✅ Does it do what the PR description says?
-- ✅ Is the commit message clear and meaningful?
-- ✅ Are there typos or formatting issues?
-- ✅ Would a beginner understand this content?
-- ✅ Is the language accessible and clear?
+#### Step 1: Open the sample file
+1. In **this** repository, open `docs/code-review-sample.md`
+2. Read the whole file. It is intentionally written with a few issues for you to find
+
+#### Step 2: Find at least two things to comment on
+Look for:
+- Typos or unclear language
+- Missing or incorrect headings
+- Inconsistent formatting (for example, list markers that do not match)
+- Missing alt text for images
+- Any accessibility or clarity problems
+
+#### Step 3: Write your review as a comment on this issue
+Post a comment on **this Challenge 12 issue** that includes:
+1. One thing the author did well (be specific - quote the line)
+2. At least one constructive suggestion (quote the line, then suggest a fix)
+3. A one-sentence verdict: would you **Approve**, **Request changes**, or **Comment** if this were a real PR, and why
+
+This is how review works when you cannot comment inline: you describe what you found and what verdict you would give.
#### Review checklist
@@ -1263,9 +1294,9 @@ Step 3: Leave inline c
**Your evidence** (fill in when closing this issue):
```text
-Review URL: https://github.com/...
-I reviewed the peer-simulation PR.
-My inline comments were about: ...
+Path used: A (PR review) or B (sample file)
+Review URL or comment: https://github.com/...
+My feedback was about: ...
My verdict was: ... because...
docs/code-review-sample.md.