+Status note (2026-07): GitHub Classroom and the
+scripts/classroom/PowerShell tooling were removed; provisioning is now the hybrid pipeline in.github/scripts/provisioning/, and peer simulation seeding happens automatically via the Student Progression Bot in each learning room. Interpretscripts/classroom/*.ps1steps below as the Student Progression Bot workflow dispatch (inputsstart_challenge,assignee).
Use this guide before a cohort is opened to learners. It is the release gate for curriculum content, GitHub Classroom deployment, Learning Room automation, accessibility, and human test coverage. Podcast and LLM-generation QA is tracked here as non-blocking unless a podcast release is explicitly in scope.
For end-to-end execution details, use admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md as the operator procedure. This guide is the release gate summary; the runbook is the required execution playbook.
The goal is simple: a facilitator should be able to create a classroom, seed test repositories, complete every challenge path, validate every generated artifact, and know exactly what remains before students arrive.
@@ -489,8 +492,8 @@Seed-LearningRoomChallenge.ps1 creates the requested starting challenge.Seed-PeerSimulation.ps1 creates the peer simulation issues, branch, file, and PR.Start-MergeConflictChallenge.ps1 creates a real conflict against the student branch.Test-LearningRoomTemplate.ps1 reports the template readiness state.+Status note (2026-07): GitHub Classroom and the
+scripts/classroom/PowerShell tooling were removed. Provisioning is the hybrid pipeline in.github/scripts/provisioning/(workflowprovision-learning-rooms.yml), and peer simulation artifacts are seeded automatically by the Student Progression Bot in each learning room. Interpretscripts/classroom/*.ps1steps below as the Student Progression Bot workflow dispatch (inputsstart_challenge,assignee);Seed-PeerSimulation.ps1steps need no action because the bot seeds and self-repairs those artifacts.
Use this runbook when you want one operational checklist that covers the full workflow:
learning-room-smoke-bAfter the student repository exists, run:
-scripts/classroom/Seed-LearningRoomChallenge.ps1 -Repository Community-Access/learning-room-smoke-a -Challenge 1 -Assignee test-student-a
-scripts/classroom/Seed-PeerSimulation.ps1 -Repository Community-Access/learning-room-smoke-a -StudentUsername test-student-aFor Day 2-only testing, seed Challenge 10 instead:
-scripts/classroom/Seed-LearningRoomChallenge.ps1 -Repository Community-Access/learning-room-smoke-a -Challenge 10 -Assignee test-student-a
-scripts/classroom/Seed-PeerSimulation.ps1 -Repository Community-Access/learning-room-smoke-a -StudentUsername test-student-aThe old scripts/classroom/ PowerShell seeding scripts were removed with GitHub Classroom. Seeding now runs through the Student Progression Bot workflow inside the student repository.
After the student repository exists, open the repo's Actions tab, choose Student Progression Bot, select Run workflow, and set:
+start_challenge: 1assignee: test-student-aFor Day 2-only testing, set start_challenge to 10 instead.
Equivalent CLI:
+gh workflow run student-progression.yml -R Community-Access/learning-room-smoke-a -f start_challenge=1 -f assignee=test-student-aSeed-PeerSimulation.ps1 creates realistic collaboration artifacts inside the student's private repo:
The progression bot seeds realistic collaboration artifacts inside the student's private repo automatically whenever it creates a challenge issue (and repairs them if any are missing):
Peer Simulation: Welcome Link Needs Context issuePeer Simulation: Review Request for Contribution Guidance issue++Status note (2026-07): GitHub Classroom and the
+scripts/classroom/PowerShell tooling described in this guide have been removed. Current cohorts use hybrid provisioning (.github/scripts/provisioning/, triggered by theprovision-learning-rooms.ymlworkflow), and peer simulation artifacts are seeded automatically by the Student Progression Bot inside each learning room. Where this guide references ascripts/classroom/*.ps1script, use the Student Progression Bot's Run workflow dispatch (inputsstart_challengeandassignee) instead. This guide is retained for the parts that are still accurate (challenge flow, bots, grading).
Single, end-to-end guide for deploying a new Git Going with GitHub workshop cohort. Covers everything from creating the classroom through post-workshop teardown. This is the only deployment document you need.
@@ -592,8 +595,7 @@Seeding the first challenge
scripts/classroom/Seed-LearningRoomChallenge.ps1 -Repository Community-Access-Classroom/learning-room-studentname -Challenge 1 -Assignee studentnameFor Day 2, use
-Challenge 10.Seeding peer simulation
-Because each GitHub Classroom repository is private, students cannot automatically see a classmate's issues or pull requests. To preserve realistic collaboration without exposing private student repos, seed peer-simulation artifacts into each student's repository:
-+scripts/classroom/Seed-PeerSimulation.ps1 -Repository Community-Access-Classroom/learning-room-studentname -StudentUsername studentnameBecause each learning room repository is private, students cannot automatically see a classmate's issues or pull requests. To preserve realistic collaboration without exposing private student repos, peer-simulation artifacts are seeded into each student's repository automatically: the Student Progression Bot creates them the first time it opens a challenge issue, and repairs them on later runs if any are missing. No facilitator action is required.
This creates two peer-simulation issues and one peer-simulation pull request. Challenges that ask students to comment, react, review, compare, or practice peer collaboration can use those seeded artifacts. If facilitators intentionally provision real buddy access, students may use real buddy repositories instead.
Triggering merge conflict practice
Challenge 7 needs a real conflict. After the student has edited
diff --git a/html/classroom/index.html b/html/classroom/index.html index a205ff45..e217502a 100644 --- a/html/classroom/index.html +++ b/html/classroom/index.html @@ -250,6 +250,9 @@docs/welcome.mdon their challenge branch and opened a pull request, run:On This Page
Workshop Deployment Guide
++Status note (2026-07): GitHub Classroom and the
+scripts/classroom/PowerShell tooling described in this guide have been removed. Current cohorts use hybrid provisioning (.github/scripts/provisioning/, triggered by theprovision-learning-rooms.ymlworkflow), and peer simulation artifacts are seeded automatically by the Student Progression Bot inside each learning room. Where this guide references ascripts/classroom/*.ps1script, use the Student Progression Bot's Run workflow dispatch (inputsstart_challengeandassignee) instead. This guide is retained for the parts that are still accurate (challenge flow, bots, grading).Single, end-to-end guide for deploying a new Git Going with GitHub workshop cohort. Covers everything from creating the classroom through post-workshop teardown. This is the only deployment document you need.
@@ -592,8 +595,7 @@Seeding the first challenge
scripts/classroom/Seed-LearningRoomChallenge.ps1 -Repository Community-Access-Classroom/learning-room-studentname -Challenge 1 -Assignee studentnameFor Day 2, use
-Challenge 10.Seeding peer simulation
-Because each GitHub Classroom repository is private, students cannot automatically see a classmate's issues or pull requests. To preserve realistic collaboration without exposing private student repos, seed peer-simulation artifacts into each student's repository:
-+scripts/classroom/Seed-PeerSimulation.ps1 -Repository Community-Access-Classroom/learning-room-studentname -StudentUsername studentnameBecause each learning room repository is private, students cannot automatically see a classmate's issues or pull requests. To preserve realistic collaboration without exposing private student repos, peer-simulation artifacts are seeded into each student's repository automatically: the Student Progression Bot creates them the first time it opens a challenge issue, and repairs them on later runs if any are missing. No facilitator action is required.
This creates two peer-simulation issues and one peer-simulation pull request. Challenges that ask students to comment, react, review, compare, or practice peer collaboration can use those seeded artifacts. If facilitators intentionally provision real buddy access, students may use real buddy repositories instead.
Triggering merge conflict practice
Challenge 7 needs a real conflict. After the student has edited
diff --git a/html/docs/06-working-with-pull-requests.html b/html/docs/06-working-with-pull-requests.html index 38fa8265..8024c072 100644 --- a/html/docs/06-working-with-pull-requests.html +++ b/html/docs/06-working-with-pull-requests.html @@ -389,7 +389,30 @@docs/welcome.mdon their challenge branch and opened a pull request, run:Challenge 6.1
Broken links and incomplete steps -Steps using the web editor:
+Steps Using the Web Editor
+This is your first challenge that uses GitHub's web editor, so take a moment with the learning cards below before you start.
+About the web editor: GitHub offers two browser-based editors. The file editor (the pencil icon on any file) edits one file at a time and is what these steps use. The full github.dev editor (press
+.(period) from the repository's Code page) is a browser-based version of Visual Studio Code with the same commands, Command Palette, and screen reader mode as the desktop app. Either works for this challenge. If you use github.dev, see Chapter 11: VS Code Interface and the VS Code Accessibility Deep Dive for full navigation guidance.++ +Screen reader users (NVDA / JAWS / VoiceOver)
+ ++
+- Find your file: On the repository's Code page, the file list is a table. Use your table reading commands to reach the file named in your issue, then press
+Enterto open it. Or pressTto open "Go to file" and type the file name.- Open the editor: With the file displayed, press
+Eto open it directly in the file editor, or pressB(NVDA/JAWS buttons quick key) to find the "Edit this file" button and pressEnter. VoiceOver: use the Buttons rotor (VO+U) to find "Edit this file" and pressVO+Space.- Alternative - github.dev: With the file displayed (or from the Code page), press
+.(period) to open the whole repository in github.dev, a web version of VS Code. Enable screen reader mode when prompted.- Find the Commit changes button: After editing, press
+B(or use the Buttons rotor) to find the button named "Commit changes..." - it sits above the editor. Activating it opens a dialog where the branch name field and "Propose changes" button live; the dialog receives focus automatically.++Sighted users
+ ++
+- Navigate to the file via the file list or the "Go to file" search.
+- Select the pencil icon (Edit this file) at the top right of the file view.
+- After editing, select the green Commit changes button above the editor to open the commit dialog.
+
- In your Learning Room repository, navigate to the file specified in your issue. Use the file tree or the "Go to file" button (
Tkeyboard shortcut).- Open the file and activate the pencil icon (Edit this file) button.
diff --git a/html/docs/11-vscode-interface.html b/html/docs/11-vscode-interface.html index 50eabb41..ed232dba 100644 --- a/html/docs/11-vscode-interface.html +++ b/html/docs/11-vscode-interface.html @@ -793,24 +793,46 @@
Learning Cards: Screen Reader Mode4. The VS Code Interface Tour
Before diving into individual features, here is how VS Code is organized. Every area is reachable by keyboard.
The Five Major Regions
--+----------------------------------------------------------+ -| Menu Bar (File, Edit, View, Go, Run, Terminal, Help) | -+------+---------------------------------------------------+ -| | | -| A | Editor Area | -| c | (your files open here) | -| t | | -| i | | -| v | | -| i +---------------------------------------------------+ -| t | | -| y | Panel (Terminal, Problems, Output, Debug Console) | -| | | -| B +---------------------------------------------------+ -| a | Status Bar (line, column, language, Git branch, | -| r | Copilot status, encoding, notifications) | -+------+---------------------------------------------------+Text description of the layout above: VS Code has five major regions arranged in a grid. The Menu Bar spans the full width across the top. Below it, the Activity Bar runs vertically along the left edge (it contains icons for Explorer, Source Control, Search, Extensions, and more). The Sidebar appears to the right of the Activity Bar and shows content for the selected activity (file tree, search results, etc.). The Editor Area fills the large central region where your files open. Below the Editor Area, the Panel stretches across the bottom and contains the Terminal, Problems, Output, and Debug Console tabs. Finally, the Status Bar runs along the very bottom showing line number, column, language mode, Git branch, Copilot status, encoding, and notifications.
++ +
++ + +Region +Where it sits +What it contains ++ +Menu Bar +Full width across the top +File, Edit, View, Go, Run, Terminal, Help menus ++ +Activity Bar +Vertical strip along the left edge +Icons for Explorer, Source Control, Search, Extensions, Accounts ++ +Sidebar +Right of the Activity Bar +Content for the selected activity (file tree, search results, etc.) ++ +Editor Area +Large central region +Your open files ++ +Panel +Below the Editor Area +Terminal, Problems, Output, Debug Console tabs ++ +Status Bar +Very bottom, full width +Line, column, language, Git branch, Copilot status, encoding, notifications +How the regions fit together: VS Code has five major regions arranged in a grid. The Menu Bar spans the full width across the top. Below it, the Activity Bar runs vertically along the left edge (it contains icons for Explorer, Source Control, Search, Extensions, and more). The Sidebar appears to the right of the Activity Bar and shows content for the selected activity (file tree, search results, etc.). The Editor Area fills the large central region where your files open. Below the Editor Area, the Panel stretches across the bottom and contains the Terminal, Problems, Output, and Debug Console tabs. Finally, the Status Bar runs along the very bottom showing line number, column, language mode, Git branch, Copilot status, encoding, and notifications.
Navigating Between Regions
diff --git a/html/docs/appendix-z-github-skills.html b/html/docs/appendix-z-github-skills.html index 4f04d282..572fbdb7 100644 --- a/html/docs/appendix-z-github-skills.html +++ b/html/docs/appendix-z-github-skills.html @@ -1000,6 +1000,7 @@
Additional Resources
- GitHub Skills homepage - browse all courses with descriptions
- GitHub Skills organization - view all course repositories directly
- GitHub Skills Discussions - ask questions and share feedback with the GitHub Skills community
+- GitHub's learning portal - GitHub's broader learning hub, including certification prep and links to Microsoft Learn modules. Accessibility varies by module, but it is a rich way to explore concepts hands-on and Microsoft Learn content is often quite accessible.
Back: Appendix Y: Workshop Materials
diff --git a/html/search-index.json b/html/search-index.json index 9970be8e..da03fa68 100644 --- a/html/search-index.json +++ b/html/search-index.json @@ -173,12 +173,6 @@ "url": "docs/05-working-with-issues.html", "body": "Working with Issues Listen to Episode 5: Working with Issues - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. Related appendices: Appendix N: Advanced Search | Appendix V: GitHub Mobile | Appendix B: Screen Reader Cheat Sheet Authoritative sources: GitHub Docs: About issues | GitHub Accessibility Guide: Issues | GitHub Accessibility Lab: CLI Guide Filing, Managing, and Participating in GitHub Issues Issues are where open source collaboration begins. This guide covers everything from finding the right issue to file a perfect bug report - all with your keyboard and screen reader. Official GitHub Accessibility Guide: GitHub publishes an NVDA-focused guide for working with issues using a screen reader at Using GitHub Issues 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 Issues Experience: This guide uses GitHub's improved Issues experience, which provides better ARIA landmark structure and live-region announcements for screen readers. 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 Issues 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): Toggle between modes with NVDA+Space (NVDA key = Insert or Caps Lock ). Use Browse Mode (the default) for reading lists, headings, and issue content. Switch to Focus Mode when typing in text fields and search boxes. Use NVDA+F7 at any time to open a list of all headings, links, form fields, buttons, and landmarks on the page - this is your orientation tool. Workshop Recommendation (Chapter 5 / Challenges 2-3) Chapter 5 is the first issue-based challenge chapter with short, confidence-building tasks. It supports Challenge 2 (File Your First Issue) and Challenge 3 (Join the Conversation). Challenge count: 2 core challenges plus one optional extension Time per challenge: under 10 minutes Evidence: issue comments and issue metadata Pattern: claim -> act -> confirm CLI getting-started principles for issue work If you prefer terminal workflows, keep this sequence: Confirm repository context first ( git remote -v and gh repo view ). Read before writing ( gh issue view <number> before commenting or editing). Keep comments focused, specific, and actionable. Verify each action from output ( gh issue list --assignee @me ). Use only documented options from gh --help and the manual. Chapter 5 Challenge Set Create your first issue - file a new issue with a clear title and description. Comment and @mention - leave a comment on a classmate's issue and tag them with an @mention. Optional extension: Add a sub-issue - break a larger issue into smaller, trackable pieces if your repository has sub-issues enabled. Branch guidance for Chapter 5: Chapter 5 focuses on issue skills. You do NOT need to create a branch or edit any files for these challenges. All your work happens in GitHub issue threads. File editing and branches start in Chapter 6. How completion works: When you finish the issue challenges, post evidence in your assigned challenge issues with links to the issue you created and the comment you posted. The facilitator reviews your issue activity directly. No pull request is required for Chapter 5. Challenge 2 Step-by-Step: Create Your First Issue Goal: File a new issue in your Learning Room repository with a specific title and a meaningful description. Agentic strategy: Issues are the prompts that wake up AI. A clear issue for a human is also a prompt for an agent. For this challenge, log an issue describing an accessibility problem or chore you wish an AI agent could fix for you. Where you are working: the Issues tab of your Learning Room repository on GitHub.com. Open your Learning Room repository in your browser. Navigate to the Issues tab (press G then I to jump there with keyboard shortcuts, or find the "Issues" link in the repository navigation). Activate the New issue button. If a template picker appears, select Open a blank issue (or choose a template if one fits). In the Title field, type a clear, specific title (at least 12 characters). Examples: "Agent Request: Add missing contributor background paragraph in welcome.md" "Keyboard shortcuts t" }, - { - "id": "docs/06-working-with-pull-requests.html", - "title": "Working with Pull Requests", - "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: 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" - }, { "id": "docs/07-merge-conflicts.html", "title": "Merge Conflicts", @@ -203,12 +197,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) For this workshop, Chapter 10 is a guided practice chapter , not a graded automation chapter. Challenge count: 1 guided walkthrough Automation check: none - notification settings are account-level and cannot be validated by the Learning Room PR bot Evidence: structured completion comment on your assigned challenge issue 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 Challenge Set Configure notifications and practice inbox management - set your watch level, use filters to find relevant notifications, and perform one inbox action. Challenge 10.1 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 Open your assigned Chapter 10 challenge issue and post a completion comment: Chapter 10 completed: - Watch level set to: Participating and @mentions - Filters tested: Review requested, Assigned - Inbox action performed: [mute / mark done] on [thread description] Close your Chapter 10 challenge issue when done. Expected Outcomes Student can configure repository watch levels to reduce noise. Student can find review requests and assigned work quickly using filters. Student can reduce notification noise with mute or done actions. If You Get Stuck Can't find the Watch button? It is near the top-right of the repository page, in the same row as Star and Fork. Notification inbox is empty? You may not have any notifications yet - that is fine. Switch to the Done tab and practice the mute/d" }, - { - "id": "docs/11-vscode-interface.html", - "title": "VS Code: Interface and Setup", - "url": "docs/11-vscode-interface.html", - "body": "VS Code: Interface and Setup Listen to Episode 11: VS Code Setup and Accessibility - a conversational audio overview covering both this chapter and Chapter 12 . Related appendices: Appendix G: VS Code Reference | Appendix B: Screen Reader Cheat Sheet Authoritative sources: VS Code Docs: User Interface | VS Code Docs: Accessibility Your Accessible Development Environment - The Foundation Day 2, Block 1 Material This chapter covers the VS Code interface: launching VS Code, signing in to GitHub, verifying Copilot is active, configuring screen reader mode, and navigating the Activity Bar, Status Bar, menus, settings, and keyboard shortcuts. For accessibility deep-dive topics (keyboard navigation, Problems panel, Terminal, Copilot Chat, Accessible Help/View/Diff, Accessibility Signals, and VS Code Speech), see Chapter 12: VS Code Accessibility Deep Dive . Prerequisites: Complete Day 1 walkthrough of GitHub's browser interface before working through VS Code material. Workshop Recommendation (Chapter 11) For this workshop, Chapter 11 is a guided setup chapter with a lightweight completion practice. Challenge count: 1 guided walkthrough Automation check: none - setup state is local/account-level and cannot be validated by the Learning Room PR bot Evidence: structured completion comment on your assigned challenge issue Pattern: open, configure, navigate, verify Chapter 11 Practice Set VS Code accessibility baseline - open VS Code (github.dev or desktop), enable screen reader mode, sign in to GitHub, verify Copilot status, and navigate core surfaces. Practice 11.1 Step-by-Step: VS Code Accessibility Baseline Goal: Confirm you can access VS Code (github.dev or desktop), enable screen reader support, sign in to GitHub, check Copilot status, and perform core navigation. Where you are working: github.dev (VS Code in the browser) or desktop VS Code if you installed it in Block 0. Estimated time: 10-15 minutes. Open your Learning Room repository on GitHub.com. Press . (the period key) on your keyboard. This launches github.dev - a full VS Code editor running in your browser. Wait a few seconds for it to load. Enable screen reader mode: Windows (NVDA/JAWS): Press Shift+Alt+F1 . You should hear an announcement confirming screen reader mode is on. Mac (VoiceOver): Screen reader mode is usually already optimized. If navigation feels wrong, open Command Palette ( Cmd+Shift+P ) and run Toggle Screen Reader Accessibility Mode . Open the Explorer panel with Ctrl+Shift+E (Mac: Cmd+Shift+E ). Your screen reader should announce the file tree. Navigate to and open README.md from the file tree. Use arrow keys to move through files and Enter to open. Open the outline/symbols view with Ctrl+Shift+O (Mac: Cmd+Shift+O ). This shows all headings and sections in the current file - a key navigation tool for screen reader users. Open the Command Palette with Ctrl+Shift+P (Mac: Cmd+Shift+P ). Type any command name (for example, Toggle Word Wrap ) and press Enter to run it. Press Escape to close without running. Check the Accounts button in the Activity Bar (bottom-left of the sidebar). If you are signed in, your screen reader announces your GitHub username. If not, activate it and sign in with GitHub. Check the Status Bar at the bottom of the window. Tab or arrow through it to find GitHub Copilot status. If Copilot is active, you hear an indicator showing it is ready. You are done when: You have successfully opened github.dev, enabled screen reader mode, signed in to GitHub, confirmed Copilot status, opened a file, viewed its outline, and run a command from the Command Palette. Completing Chapter 11: Submit Your Evidence Return to GitHub.com, open the assigned setup or Day 2 readiness issue, and post a completion comment: Chapter 11 completed: - Opened github.dev: yes / no - Screen reader mode enabled: yes / no - Signed in to GitHub: yes / no - Copilot status checked: yes / no - Opened file in Explorer: yes / no - Opened outline/symbols: yes / no - Opened Command Palette: yes / no If any step was "no," add a note explaining where you got stuck so the facilitator can help. Close the assigned setup or readiness issue when done. Expected Outcomes Student can launch and navigate github.dev or desktop VS Code. Student can enable screen reader mode and hear navigation announcements. Student has signed in to GitHub and can see their account status. Student has verified GitHub Copilot is active (or knows it requires desktop VS Code). Student can open core navigation surfaces (Explorer, Outline, Command Palette). Student is ready for VS Code-based contribution chapters (6-16). If You Get Stuck Nothing happens when you press . ? Make sure you are on the repository's main page (not inside an issue or PR). The . shortcut only works on repository code pages. Screen reader mode toggle did not announce anything? Open Command Palette ( Ctrl+Shift+P ) and type Screen Reader to find the toggle manually. Explorer panel is empty? VS Code may stil" - }, { "id": "docs/12-vscode-accessibility.html", "title": "VS Code: Accessibility Deep Dive", @@ -473,12 +461,6 @@ "url": "docs/appendix-y-workshop-materials.html", "body": "Appendix Y: Accessing and Downloading Workshop Materials Listen to Episode 42: Accessing Workshop Materials - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. Reference companion to: Chapter 00: Pre-Workshop Setup Authoritative source: Community-Access/git-going-with-github How to Get, Read, and Keep These Documents Why this appendix exists: The workshop content is available in multiple formats - Markdown source files, pre-built HTML pages, and a live GitHub Pages site. This guide explains how to access each format, download materials for offline use, and keep your copy up to date. Learning Cards: Accessing Workshop Materials Screen reader users The GitHub Pages site includes skip-to-content links and ARIA landmarks -- press D (NVDA) or R (JAWS) to jump to the main content landmark on any page On GitHub.com, press T on the repository's main page to open the file finder -- type any filename to jump directly to it without navigating the file tree After cloning the repository, open it in VS Code and use the Explorer panel ( Ctrl+Shift+E ) to browse the file tree with arrow keys Low vision users The HTML version in the html/ folder provides the most polished reading experience with styled, navigable pages that work offline in any browser For reading Markdown source files, use VS Code's built-in preview ( Ctrl+Shift+V ) which renders headings, links, and code blocks in a formatted view When downloading a ZIP from GitHub, the Code button and its dropdown appear near the top of the repository page -- look for the green button Sighted users Three ways to access materials: GitHub Pages site (online, styled), GitHub.com (browse rendered Markdown), or local clone (offline, editable) The repository's docs/ folder contains all Markdown source files; the html/ folder contains pre-built HTML versions of every page Use git clone for a full copy you can update with git pull -- ZIP downloads are snapshots that do not update automatically Table of Contents Browsing Online (GitHub Pages) Reading on GitHub.com Downloading Everything Downloading Individual Files What's in Each Folder Offline Reading Keeping Your Copy Updated Which Format Should I Use? 1. Browsing Online (GitHub Pages) If the facilitator has enabled GitHub Pages for this repository, the workshop materials are available as a website at a URL like: https://<organization>.github.io/Learning-Room/ Your facilitator will share the exact URL. Once you have it: Open the URL in your browser The landing page ( index.html ) is the workshop homepage - equivalent to the README Use headings ( H key in NVDA/JAWS browse mode) to navigate within any page All internal links between chapters and appendices work - click any cross-reference to go directly to that page Bookmark the URL for quick access during the workshop Screen reader tip: The HTML pages include skip-to-content links, breadcrumb navigation, and ARIA landmarks. Press D (NVDA) or R (JAWS) to jump to the main landmark on any page. For details on how GitHub Pages works, see Appendix P - Publishing with GitHub Pages . 2. Reading on GitHub.com You can read every file directly on GitHub.com without downloading anything: Go to the repository page (your facilitator will share the link) The README renders automatically as the repository homepage Click into the docs/ folder to see all chapters and appendices Click any .md file - GitHub renders it as formatted text with headings, links, and code blocks Navigating the repository with a screen reader File list: The repository file listing is a grid. Use T to jump to the file table, then arrow keys to navigate rows File content: Once inside a file, GitHub renders the Markdown. Use H to navigate headings Breadcrumbs: At the top of each file view, breadcrumb links show the path (e.g., Learning-Room / docs / 06-working-with-pull-requests.md ). Use these to navigate back Go to File shortcut: Press T on the repository's main page to open the file finder - type any filename to jump to it 3. Downloading Everything Option A: Clone with Git (recommended) Cloning gives you a full copy of the repository that you can update later with git pull : # Clone the repository git clone https://github.com/community-access/git-going-with-github.git # Move into the folder cd Learning-Room After cloning, every file (Markdown source, HTML output, scripts, learning-room materials) is on your computer. Screen reader tip: After cloning, open the folder in VS Code ( code . ) and use the Explorer panel ( Ctrl+Shift+E ) to browse the file tree. Press Enter on any file to open it in the editor. Option B: Download ZIP (no Git required) If you do not have Git installed or prefer not to use the command line: Go to the repository page on GitHub.com Press T to find the file finder, or navigate to the green Code button (it is a dropdown button near the top of the file listing) Activate the Code button - a dr" }, - { - "id": "docs/appendix-z-github-skills.html", - "title": "Appendix Z: GitHub Skills - Complete Course Catalog", - "url": "docs/appendix-z-github-skills.html", - "body": "Appendix Z: GitHub Skills - Complete Course Catalog Listen to Episode 43: GitHub Skills - Complete Course Catalog - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. Reference companion to: Chapter 00: Pre-Workshop Setup | Also relevant: Chapter 22: What Comes Next Authoritative source: GitHub Skills GitHub Skills is GitHub's free, self-paced interactive learning platform. Every course runs entirely inside GitHub - no external site, no separate login, no video. You copy a course repository to your own account, and an automated bot named Mona teaches you through real issues and pull requests. This appendix catalogs every available GitHub Skills module, organized into learning paths that build on the skills you practiced in this workshop. Use it as a roadmap for continued learning after Day 2. Learning Cards: How GitHub Skills Works Screen reader users Every GitHub Skills course runs inside a standard GitHub repository -- the screen reader navigation skills from this workshop (heading nav, issue reading, PR workflows) apply directly After copying a course with "Use this template," navigate to the Issues tab ( G then I ) and press H or 3 to find "Step 1:" -- this is where Mona's first lesson appears Mona posts feedback as issue comments -- press 9 (NVDA/JAWS) to jump to the comments section and read her instructions Low vision users Course content appears as standard GitHub issues and comments -- your existing GitHub theme and font size settings apply automatically Mona's step numbers appear as issue titles with "Step 1:", "Step 2:" prefixes -- scan the Issues list for these numbered titles to track your progress Course completion is indicated when Mona closes the final issue with a success message -- look for the purple "Closed" badge Sighted users Start any course by clicking "Start course" on the module page, then "Use this template" then "Create a new repository" -- Mona activates within 20 seconds Each step appears as a new issue or comment in your copied repository -- follow the instructions, complete the task, and Mona advances you automatically Track progress by watching the Issues tab -- open issues are pending steps, closed issues are completed steps How GitHub Skills Works Each course follows the same pattern: Navigate to the course URL and select "Start course" GitHub copies the course repository to your account Mona (GitHub's automated learning bot) opens an issue with Step 1 instructions within 20 seconds You complete the task described in the issue (create a branch, edit a file, open a PR) Mona detects your action, validates it, and posts the next step as a comment or new issue Repeat until Mona closes the final issue with a completion message All interaction happens through GitHub's standard interface. The screen reader navigation skills from this workshop - heading navigation, landmark jumping, issue and PR workflows - apply directly. For detailed screen reader navigation instructions, see Appendix U Section 3 (GitHub Skills) . Courses Used in This Workshop These three modules are integrated into the Day 1 agenda. You complete them during the workshop with facilitator guidance. The following table lists the three GitHub Skills modules used during Day 1, with their workshop block and what each teaches. Module Workshop Block What Mona Teaches Link Introduction to GitHub Day 1, Blocks 1-3 Branches, commits, pull requests, merge Start course Communicate Using Markdown Day 1, Block 3 Headings, emphasis, links, code blocks, task lists, tables Start course Review Pull Requests Day 1, Block 4 Assign reviewers, leave comments, suggest changes, approve, merge Start course If you did not finish these during the workshop, complete them first before moving to the paths below. Learning Paths The remaining courses are organized into six learning paths. Each path builds on skills from this workshop and progresses from introductory to advanced. You do not need to complete every path - choose the ones that match your goals. Learning Cards: Navigating Learning Paths Screen reader users The six learning paths below are organized as H3 headings with tables listing courses in recommended order -- press 3 to jump between paths, then T to enter each course table Each course link is in the rightmost "Link" column of the table -- navigate to it with arrow keys after entering the table Use the Personal Completion Checklist at the bottom of this appendix as a progress tracker -- copy it into a GitHub issue or personal notes file Low vision users Each learning path table has columns for Order, Module, Duration, Prerequisite, What You Learn, and Link -- widen your browser if columns appear truncated at high zoom Course durations range from 30 minutes to 2 hours -- the Duration column helps you plan which courses fit your" - }, { "id": "docs/course-guide.html", "title": "Course Guide", @@ -497,6 +479,24 @@ "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", + "url": "docs/11-vscode-interface.html", + "body": "VS Code: Interface and Setup Listen to Episode 11: VS Code Setup and Accessibility - a conversational audio overview covering both this chapter and Chapter 12 . Related appendices: Appendix G: VS Code Reference | Appendix B: Screen Reader Cheat Sheet Authoritative sources: VS Code Docs: User Interface | VS Code Docs: Accessibility Your Accessible Development Environment - The Foundation Day 2, Block 1 Material This chapter covers the VS Code interface: launching VS Code, signing in to GitHub, verifying Copilot is active, configuring screen reader mode, and navigating the Activity Bar, Status Bar, menus, settings, and keyboard shortcuts. For accessibility deep-dive topics (keyboard navigation, Problems panel, Terminal, Copilot Chat, Accessible Help/View/Diff, Accessibility Signals, and VS Code Speech), see Chapter 12: VS Code Accessibility Deep Dive . Prerequisites: Complete Day 1 walkthrough of GitHub's browser interface before working through VS Code material. Workshop Recommendation (Chapter 11) For this workshop, Chapter 11 is a guided setup chapter with a lightweight completion practice. Challenge count: 1 guided walkthrough Automation check: none - setup state is local/account-level and cannot be validated by the Learning Room PR bot Evidence: structured completion comment on your assigned challenge issue Pattern: open, configure, navigate, verify Chapter 11 Practice Set VS Code accessibility baseline - open VS Code (github.dev or desktop), enable screen reader mode, sign in to GitHub, verify Copilot status, and navigate core surfaces. Practice 11.1 Step-by-Step: VS Code Accessibility Baseline Goal: Confirm you can access VS Code (github.dev or desktop), enable screen reader support, sign in to GitHub, check Copilot status, and perform core navigation. Where you are working: github.dev (VS Code in the browser) or desktop VS Code if you installed it in Block 0. Estimated time: 10-15 minutes. Open your Learning Room repository on GitHub.com. Press . (the period key) on your keyboard. This launches github.dev - a full VS Code editor running in your browser. Wait a few seconds for it to load. Enable screen reader mode: Windows (NVDA/JAWS): Press Shift+Alt+F1 . You should hear an announcement confirming screen reader mode is on. Mac (VoiceOver): Screen reader mode is usually already optimized. If navigation feels wrong, open Command Palette ( Cmd+Shift+P ) and run Toggle Screen Reader Accessibility Mode . Open the Explorer panel with Ctrl+Shift+E (Mac: Cmd+Shift+E ). Your screen reader should announce the file tree. Navigate to and open README.md from the file tree. Use arrow keys to move through files and Enter to open. Open the outline/symbols view with Ctrl+Shift+O (Mac: Cmd+Shift+O ). This shows all headings and sections in the current file - a key navigation tool for screen reader users. Open the Command Palette with Ctrl+Shift+P (Mac: Cmd+Shift+P ). Type any command name (for example, Toggle Word Wrap ) and press Enter to run it. Press Escape to close without running. Check the Accounts button in the Activity Bar (bottom-left of the sidebar). If you are signed in, your screen reader announces your GitHub username. If not, activate it and sign in with GitHub. Check the Status Bar at the bottom of the window. Tab or arrow through it to find GitHub Copilot status. If Copilot is active, you hear an indicator showing it is ready. You are done when: You have successfully opened github.dev, enabled screen reader mode, signed in to GitHub, confirmed Copilot status, opened a file, viewed its outline, and run a command from the Command Palette. Completing Chapter 11: Submit Your Evidence Return to GitHub.com, open the assigned setup or Day 2 readiness issue, and post a completion comment: Chapter 11 completed: - Opened github.dev: yes / no - Screen reader mode enabled: yes / no - Signed in to GitHub: yes / no - Copilot status checked: yes / no - Opened file in Explorer: yes / no - Opened outline/symbols: yes / no - Opened Command Palette: yes / no If any step was "no," add a note explaining where you got stuck so the facilitator can help. Close the assigned setup or readiness issue when done. Expected Outcomes Student can launch and navigate github.dev or desktop VS Code. Student can enable screen reader mode and hear navigation announcements. Student has signed in to GitHub and can see their account status. Student has verified GitHub Copilot is active (or knows it requires desktop VS Code). Student can open core navigation surfaces (Explorer, Outline, Command Palette). Student is ready for VS Code-based contribution chapters (6-16). If You Get Stuck Nothing happens when you press . ? Make sure you are on the repository's main page (not inside an issue or PR). The . shortcut only works on repository code pages. Screen reader mode toggle did not announce anything? Open Command Palette ( Ctrl+Shift+P ) and type Screen Reader to find the toggle manually. Explorer panel is empty? VS Code may stil" + }, + { + "id": "docs/06-working-with-pull-requests.html", + "title": "Working with Pull Requests", + "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: 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" + }, + { + "id": "docs/appendix-z-github-skills.html", + "title": "Appendix Z: GitHub Skills - Complete Course Catalog", + "url": "docs/appendix-z-github-skills.html", + "body": "Appendix Z: GitHub Skills - Complete Course Catalog Listen to Episode 43: GitHub Skills - Complete Course Catalog - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. Reference companion to: Chapter 00: Pre-Workshop Setup | Also relevant: Chapter 22: What Comes Next Authoritative source: GitHub Skills GitHub Skills is GitHub's free, self-paced interactive learning platform. Every course runs entirely inside GitHub - no external site, no separate login, no video. You copy a course repository to your own account, and an automated bot named Mona teaches you through real issues and pull requests. This appendix catalogs every available GitHub Skills module, organized into learning paths that build on the skills you practiced in this workshop. Use it as a roadmap for continued learning after Day 2. Learning Cards: How GitHub Skills Works Screen reader users Every GitHub Skills course runs inside a standard GitHub repository -- the screen reader navigation skills from this workshop (heading nav, issue reading, PR workflows) apply directly After copying a course with "Use this template," navigate to the Issues tab ( G then I ) and press H or 3 to find "Step 1:" -- this is where Mona's first lesson appears Mona posts feedback as issue comments -- press 9 (NVDA/JAWS) to jump to the comments section and read her instructions Low vision users Course content appears as standard GitHub issues and comments -- your existing GitHub theme and font size settings apply automatically Mona's step numbers appear as issue titles with "Step 1:", "Step 2:" prefixes -- scan the Issues list for these numbered titles to track your progress Course completion is indicated when Mona closes the final issue with a success message -- look for the purple "Closed" badge Sighted users Start any course by clicking "Start course" on the module page, then "Use this template" then "Create a new repository" -- Mona activates within 20 seconds Each step appears as a new issue or comment in your copied repository -- follow the instructions, complete the task, and Mona advances you automatically Track progress by watching the Issues tab -- open issues are pending steps, closed issues are completed steps How GitHub Skills Works Each course follows the same pattern: Navigate to the course URL and select "Start course" GitHub copies the course repository to your account Mona (GitHub's automated learning bot) opens an issue with Step 1 instructions within 20 seconds You complete the task described in the issue (create a branch, edit a file, open a PR) Mona detects your action, validates it, and posts the next step as a comment or new issue Repeat until Mona closes the final issue with a completion message All interaction happens through GitHub's standard interface. The screen reader navigation skills from this workshop - heading navigation, landmark jumping, issue and PR workflows - apply directly. For detailed screen reader navigation instructions, see Appendix U Section 3 (GitHub Skills) . Courses Used in This Workshop These three modules are integrated into the Day 1 agenda. You complete them during the workshop with facilitator guidance. The following table lists the three GitHub Skills modules used during Day 1, with their workshop block and what each teaches. Module Workshop Block What Mona Teaches Link Introduction to GitHub Day 1, Blocks 1-3 Branches, commits, pull requests, merge Start course Communicate Using Markdown Day 1, Block 3 Headings, emphasis, links, code blocks, task lists, tables Start course Review Pull Requests Day 1, Block 4 Assign reviewers, leave comments, suggest changes, approve, merge Start course If you did not finish these during the workshop, complete them first before moving to the paths below. Learning Paths The remaining courses are organized into six learning paths. Each path builds on skills from this workshop and progresses from introductory to advanced. You do not need to complete every path - choose the ones that match your goals. Learning Cards: Navigating Learning Paths Screen reader users The six learning paths below are organized as H3 headings with tables listing courses in recommended order -- press 3 to jump between paths, then T to enter each course table Each course link is in the rightmost "Link" column of the table -- navigate to it with arrow keys after entering the table Use the Personal Completion Checklist at the bottom of this appendix as a progress tracker -- copy it into a GitHub issue or personal notes file Low vision users Each learning path table has columns for Order, Module, Duration, Prerequisite, What You Learn, and Link -- widen your browser if columns appear truncated at high zoom Course durations range from 30 minutes to 2 hours -- the Duration column helps you plan which courses fit your" + }, { "id": "agents/image alt text agent/agents/image-alt-text.agent.html", "title": "image-alt-text.agent", @@ -2117,12 +2117,6 @@ "url": "admin/HYBRID_REVIEW_INDEX.html", "body": "Hybrid Plan: Review Index This is the single entry point for reviewing everything built for the Hybrid plan (Option C): a dependable, GitHub-native provisioning core that replaces GitHub Classroom, plus an optional, fully accessible Flask companion at the edges. It is described in golden.md (vision) and specified in SPEC.md (technical spec). Most functional files stay where the repository expects them (workflows under .github/workflows/ , Node scripts under .github/scripts/ ) so the system keeps working. This page points you to all of them, grouped by concern, in a suggested reading order. Suggested review order Start with the vision and spec so the rest has context. Read the deployment guide to see how it is operated end to end. Skim the provisioning core (the critical path). Skim the optional companion (the edges). Confirm the tests and CI wiring. 1. Planning and specification (repo root) File What it is golden.md Vision document for the Hybrid plan. SPEC.md Technical specification, including an Implementation status section. roster.schema.json JSON Schema for the owned roster of record. 2. Documentation ( admin/ ) File What it is HYBRID_DEPLOYMENT_GUIDE.md Phased, verification-driven deployment guide (start here to operate it). OWNED_PROVISIONING.md Operator guide: data model, running provisioning, failure recovery. COHORT_PROVISIONING.md Existing cohort doc, now pointing at the owned subsystem. examples/roster.example.json Example owned roster you can copy. 3. Provisioning core ( .github/scripts/provisioning/ ) — the critical path These stay in place because the workflow and CLI load them from here. File Responsibility .github/scripts/provisioning/roster.js Owned roster contract: parse, validate, upsert, serialize, redact. Keyed on (github_handle, cohort_id) . .github/scripts/provisioning/progress.js Derives learner progress from owned signals. .github/scripts/provisioning/github-app-auth.js RS256 GitHub App JWT + installation-token minting (Node crypto , no deps). .github/scripts/provisioning/github-client.js Minimal REST client; fetch adapter (CLI) + fromOctokit adapter (workflows). .github/scripts/provisioning/provision-core.js Idempotent, serial, backoff-aware provisioning algorithm. .github/scripts/provisioning/provision-cli.js Standalone CLI runner. .github/scripts/provisioning/__tests__/ 6 test files, 55 tests, run with node --test . 4. Optional accessible companion ( companion/ ) — the edges Fully self-contained Flask app. It writes a local roster.json ; a separate sync job commits it to the admin repo. It deliberately does not push to GitHub itself. Path What it is companion/README.md Companion overview, run, and security/accessibility notes. companion/app.py Flask application factory and routes. companion/roster_store.py Python mirror of the owned roster contract. companion/templates/ WCAG 2.2 AA templates (base, register, success, login, dashboard, error). companion/static/styles.css Accessible styling. companion/requirements.txt Python dependencies (Flask). companion/tests/ 2 test files, 25 tests ( python -m unittest ). 5. CI wiring and commands File What changed .github/workflows/provision-learning-rooms.yml New provisioning workflow: scheduled + manual dry_run ; github-app and actions-bot modes. .github/workflows/automation-tests.yml Added provisioning + companion test steps. package.json Added test:provisioning script. Run the suites locally: # Existing automation tests npm run test :automation # Provisioning subsystem (Node, no install needed) npm run test :provisioning # Flask companion (Python) cd companion python -m venv .venv && .venv/bin/pip install -r requirements.txt .venv/bin/python -m unittest discover -s tests Commits on this branch The work landed in two commits on feature/hybrid-owned-provisioning : d6dd05ddc — provisioning core, companion, tests, docs, schema, CI wiring. 89bc204bd — Hybrid deployment guide + cross-link. This index adds one more documentation commit. Nothing was moved out of its conventional location, so the workflows and CLI continue to resolve their imports. Authoritative Sources Use these official references when you need the current source of truth for facts in this document. GitHub Actions workflows Authenticating as a GitHub App installation Web Content Accessibility Guidelines (WCAG) 2.2 Section-Level Source Map Use this map to verify facts for each major section in this file. Planning and specification, Provisioning core: golden.md , SPEC.md CI wiring and commands: GitHub Actions workflows Provisioning core, Documentation: Authenticating as a GitHub App installation Optional accessible companion: Web Content Accessibility Guidelines (WCAG) 2.2" }, - { - "id": "admin/LEARNING-ROOM-E2E-QA-RUNBOOK.html", - "title": "Learning Room End-to-End QA Runbook (Registration to Student Completion)", - "url": "admin/LEARNING-ROOM-E2E-QA-RUNBOOK.html", - "body": "Learning Room End-to-End QA Runbook (Registration to Student Completion) Use this runbook when you want one operational checklist that covers the full workflow: Registration intake and validation. GitHub Classroom deployment and assignment setup. Test account acceptance and repository seeding. Full student walkthrough of every challenge path. Release sign-off evidence for go-live. This runbook intentionally excludes podcast validation work. Everything else is in scope: registration flow, classroom deployment, assignment configuration, template readiness, student progression, PR validation, content validation, skills progression, autograder behavior, challenge completion tracking, and chapter-by-chapter curriculum review. Scope and Audience This runbook is for facilitators, QA leads, and admins who need to verify the complete workshop flow from administrator setup to student completion. Scope Boundaries In scope: Registration workflow behavior and classroom invitation handoff. Classroom assignment creation and autograding configuration. Learning Room automation workflows and facilitator scripts. Full curriculum walkthrough (chapters and appendices). Student challenge journey (1-16) and bonus challenge tracking (A-E). QA evidence capture, defect logging, and release sign-off. Out of scope: Podcast generation, podcast validation, and RSS audio feed checks. Canonical Source Files Used by This Runbook Table: Source files consolidated by this runbook Area Source file Registration entry page REGISTER.md Registration automation admin REGISTRATION-ADMIN.md Registration automation quickstart REGISTRATION-QUICKSTART.md Registration workflow logic .github/workflows/registration.yml Classroom deployment classroom/README.md Assignment copy and autograding setup admin/classroom/README.md Human challenge walkthrough classroom/HUMAN_TEST_MATRIX.md Challenge definitions docs/CHALLENGES.md Student starting path docs/get-going.md Grading criteria classroom/grading-guide.md Release gate baseline GO-LIVE-QA-GUIDE.md Support hub operations SUPPORT_HUB_OPERATIONS.md Table: QA validation checkpoints for registration and classroom automation Table: Student journey checkpoints and expected artifacts Table: Label color and purpose for registration automation Table: Screen reader options for workshop setup Table: Accessibility improvements for screen reader users Required Accounts, Access, and Tools Complete this section before Phase 1. Facilitator admin account ( accesswatch ) with Owner access to both Community-Access and Community-Access-Classroom . Dedicated non-admin test student account for acceptance and full challenge walkthrough. This must be a separate GitHub account that is not an owner or member of either organization. Access to classroom.github.com while signed in as accesswatch . Access to repository settings for Community-Access/git-going-with-github (secrets and variables). Local clone of this repository with PowerShell available. GitHub CLI ( gh ) installed and authenticated as accesswatch for optional verification commands. Critical Precondition Gates (No-Go if any fail) Complete all items below before any cohort launch actions. Facilitator account accesswatch can access both organizations: Community-Access (the workshop and code repository organization) Community-Access-Classroom (the GitHub Classroom organization where student repos are created) accesswatch has a verified email address on its GitHub account and can create and edit Classroom assignments at classroom.github.com . Dedicated non-admin test student account exists and can accept invites. gh auth status succeeds for accesswatch in local terminal. Template repository exists and is set as template repo: Community-Access/learning-room-template Template repository Actions settings allow required automation behavior: Actions enabled GITHUB_TOKEN default workflow permissions include write where required Allow GitHub Actions to create and approve pull requests enabled Registration automation settings are correct when using registration-to-classroom handoff: Variables CLASSROOM_DAY1_ASSIGNMENT_URL and CLASSROOM_DAY2_ASSIGNMENT_URL are set in Community-Access/git-going-with-github Registration entry configuration exists and is valid: Issue form template workshop-registration.yml exists Required labels exist: registration , duplicate , waitlist While signed in as accesswatch , opening classroom.github.com shows the Community-Access-Classroom classroom organization. If any precondition fails, stop and resolve before proceeding. Exact Setup Steps for Keys, Permissions, Settings, and Template Currency Use this section when you need literal setup steps (not only validation checks). A. Confirm facilitator account and organization access You are performing all steps below as accesswatch . If you are currently signed in to GitHub as a different account, sign out first and sign in as accesswatch before continuing. Go to github.com and confirm the top-right avatar shows acce" - }, { "id": "admin/PODCASTS.html", "title": "Podcasts", @@ -2195,6 +2189,12 @@ "url": "admin/OWNED_PROVISIONING.html", "body": "Owned, GitHub-native Provisioning This is the operator guide for the GitHub-native provisioning subsystem: the owned replacement for GitHub Classroom described in golden.md and specified in SPEC.md sections 6 and 7. It explains the data model, how to run provisioning, how to recover from failure, and how the optional Flask companion fits in at the edges. For first-time setup and deployment, follow the Hybrid Deployment Guide first. To review the whole deliverable from one place, see HYBRID_REVIEW_INDEX.md . The whole point of this subsystem is captured in one promise: a vendor sunset is a non-event. Provisioning, roster, and progress are owned and reconstructable, so no future change to GitHub Classroom can strand a cohort. Table of contents Why this exists The three owned sources of truth How provisioning works One-time setup Running a cohort Idempotency and self-healing Failure modes and recovery The optional Flask companion Security and least privilege Local development and testing Authoritative Sources Why this exists GitHub Classroom does only two things for this workshop: it copies a template repository into a per-student private repository, and it maps a GitHub identity to a roster entry. Everything else already lives in infrastructure the project controls. This subsystem replaces those two things with code we own, so the critical learner path no longer depends on a single vendor feature. The three owned sources of truth The decoupling contract requires three owned, reconstructable records. See SPEC.md section 6 for the full schemas. Roster of record. One canonical JSON document mapping each learner handle to cohort, path, provisioning state, and progression status. Lives in the private admin repository as roster.json . Schema and validation live in roster.js and roster.schema.json . An example is in examples/roster.example.json . Progress of record. Never authored by a vendor. Derived from deterministic signals the project controls (challenge issue state, PR closing keywords, labels, and the plain-text signals ack and day1-complete ) by progress.js . Provisioning of record. An append-only log of provisioning attempts and outcomes ( provisioning-log.json ), sufficient to prove a repository is correctly seeded and to safely re-run. Reconstruction rule: running the idempotent provisioning action against the roster reproduces a healthy state for every learner, with no third party involved. How provisioning works The provisioning subsystem is plain Node with no third-party dependencies (it uses built-in crypto and global fetch ). The pieces are: File Role roster.js Owned roster: parse, validate, upsert, serialize, redact progress.js Derive learner status from deterministic signals github-app-auth.js Sign an App JWT and mint a short-lived installation token github-client.js Minimal GitHub REST client (fetch or Octokit) provision-core.js The idempotent, serial, backoff provisioning algorithm provision-cli.js Standalone runner used by the workflow provision-learning-rooms.yml Scheduled and manual workflow wrapper The algorithm (SPEC.md section 7.2b) runs serially with a short delay and exponential backoff, not a parallel fan-out, to stay clear of GitHub secondary rate limits. For each pending or failed learner it: checks whether the repository exists; creates it from the template if not; ensures the learner is a collaborator; verifies the required workflow set is present; and records the outcome. Every step is safe to repeat. One-time setup Provisioning supports two modes via the PROVISIONING_MODE variable. Production: GitHub App ( github-app ) A GitHub App is the production identity because it is not tied to a human account, mints short-lived tokens, and uses fine-grained least-privilege permissions. Create a GitHub App in the Community-Access organization with only these permissions: Repository administration (write), Contents (write), Metadata (read), and optionally Issues (write). Nothing more. Install the App on the organization. Creating student repositories requires an organization-wide installation (repository creation cannot be granted through a selected-repositories installation). Do not skip this step: an App that exists but is not installed fails every token mint with HTTP 404. Generate a private key (PEM). Store these as repository or environment secrets: PROVISIONING_APP_ID PROVISIONING_APP_PRIVATE_KEY (the PEM contents) PROVISIONING_APP_INSTALLATION_ID (optional; when unset, provisioning discovers the installation from the App itself, which also survives re-installation) Set repository variables: PROVISIONING_MODE = github-app LEARNING_ROOM_TEMPLATE_REPO = Community-Access/learning-room-template PROVISIONING_STUDENT_OWNER = Community-Access ADMIN_ROSTER_REPO = the private admin repository holding roster.json PROVISIONING_COHORT_ID = the cohort that new enrollees are added to Provide PRIVATE_STUDENT_DATA_TOKEN , a token that can check out and push to the admin roster repository. Verify credent" }, + { + "id": "admin/LEARNING-ROOM-E2E-QA-RUNBOOK.html", + "title": "Learning Room End-to-End QA Runbook (Registration to Student Completion)", + "url": "admin/LEARNING-ROOM-E2E-QA-RUNBOOK.html", + "body": "Learning Room End-to-End QA Runbook (Registration to Student Completion) Status note (2026-07): GitHub Classroom and the scripts/classroom/ PowerShell tooling were removed. Provisioning is the hybrid pipeline in .github/scripts/provisioning/ (workflow provision-learning-rooms.yml ), and peer simulation artifacts are seeded automatically by the Student Progression Bot in each learning room. Interpret scripts/classroom/*.ps1 steps below as the Student Progression Bot workflow dispatch (inputs start_challenge , assignee ); Seed-PeerSimulation.ps1 steps need no action because the bot seeds and self-repairs those artifacts. Use this runbook when you want one operational checklist that covers the full workflow: Registration intake and validation. GitHub Classroom deployment and assignment setup. Test account acceptance and repository seeding. Full student walkthrough of every challenge path. Release sign-off evidence for go-live. This runbook intentionally excludes podcast validation work. Everything else is in scope: registration flow, classroom deployment, assignment configuration, template readiness, student progression, PR validation, content validation, skills progression, autograder behavior, challenge completion tracking, and chapter-by-chapter curriculum review. Scope and Audience This runbook is for facilitators, QA leads, and admins who need to verify the complete workshop flow from administrator setup to student completion. Scope Boundaries In scope: Registration workflow behavior and classroom invitation handoff. Classroom assignment creation and autograding configuration. Learning Room automation workflows and facilitator scripts. Full curriculum walkthrough (chapters and appendices). Student challenge journey (1-16) and bonus challenge tracking (A-E). QA evidence capture, defect logging, and release sign-off. Out of scope: Podcast generation, podcast validation, and RSS audio feed checks. Canonical Source Files Used by This Runbook Table: Source files consolidated by this runbook Area Source file Registration entry page REGISTER.md Registration automation admin REGISTRATION-ADMIN.md Registration automation quickstart REGISTRATION-QUICKSTART.md Registration workflow logic .github/workflows/registration.yml Classroom deployment classroom/README.md Assignment copy and autograding setup admin/classroom/README.md Human challenge walkthrough classroom/HUMAN_TEST_MATRIX.md Challenge definitions docs/CHALLENGES.md Student starting path docs/get-going.md Grading criteria classroom/grading-guide.md Release gate baseline GO-LIVE-QA-GUIDE.md Support hub operations SUPPORT_HUB_OPERATIONS.md Table: QA validation checkpoints for registration and classroom automation Table: Student journey checkpoints and expected artifacts Table: Label color and purpose for registration automation Table: Screen reader options for workshop setup Table: Accessibility improvements for screen reader users Required Accounts, Access, and Tools Complete this section before Phase 1. Facilitator admin account ( accesswatch ) with Owner access to both Community-Access and Community-Access-Classroom . Dedicated non-admin test student account for acceptance and full challenge walkthrough. This must be a separate GitHub account that is not an owner or member of either organization. Access to classroom.github.com while signed in as accesswatch . Access to repository settings for Community-Access/git-going-with-github (secrets and variables). Local clone of this repository with PowerShell available. GitHub CLI ( gh ) installed and authenticated as accesswatch for optional verification commands. Critical Precondition Gates (No-Go if any fail) Complete all items below before any cohort launch actions. Facilitator account accesswatch can access both organizations: Community-Access (the workshop and code repository organization) Community-Access-Classroom (the GitHub Classroom organization where student repos are created) accesswatch has a verified email address on its GitHub account and can create and edit Classroom assignments at classroom.github.com . Dedicated non-admin test student account exists and can accept invites. gh auth status succeeds for accesswatch in local terminal. Template repository exists and is set as template repo: Community-Access/learning-room-template Template repository Actions settings allow required automation behavior: Actions enabled GITHUB_TOKEN default workflow permissions include write where required Allow GitHub Actions to create and approve pull requests enabled Registration automation settings are correct when using registration-to-classroom handoff: Variables CLASSROOM_DAY1_ASSIGNMENT_URL and CLASSROOM_DAY2_ASSIGNMENT_URL are set in Community-Access/git-going-with-github Registration entry configuration exists and is valid: Issue form template workshop-registration.yml exists Required labels exist: registration , duplicate , waitlist While signed in as accesswatch , opening classroom.github.com shows the Communi" + }, { "id": "classroom/assignment-issue-template.html", "title": "Assignment Issue Template Reference", @@ -2207,18 +2207,6 @@ "url": "classroom/grading-guide.html", "body": "Facilitator Grading Guide How to evaluate student work across the 16 core challenges and 5 bonus challenges. Grading Philosophy This is a learning workshop, not a competitive course. The grading system measures participation and engagement, not perfection. Completion, not correctness: If a student attempted the challenge and produced evidence, they completed it Effort over elegance: A messy first attempt that shows learning is better than a polished copy-paste Partial credit always: Any progress counts. No student should feel like they failed. Automated Checks Automated checks run as GitHub Actions workflows shipped inside each student repo (from Community-Access/learning-room-template ). They check for: Existence of files, branches, and commits Presence of required fields in templates Absence of merge conflict markers Automated checks handle the objective criteria. Facilitator judgment handles everything else. What is auto-checked today (see workflow files under .github/workflows/autograder-*.yml in the template repo, and admin/classroom/autograding-setup.md for the full mapping): Day 1: Challenges 2, 5, 6, 7 (issue filed, commit on branch, PR with Closes/Fixes/Resolves , no conflict markers) Day 2: Challenges 10, 14, 16 (local commit on branch, custom issue template with name / description , agent file with frontmatter and required sections) The (auto) tag in the per-challenge tables below marks rows where an autograder workflow will post pass/fail results as an issue or PR comment. All other rows require facilitator review. Per-Challenge Grading Day 1 Challenges (01-09) # Challenge Evidence Complete if... 01 Find Your Way Around Issue comment listing findings Student explored multiple tabs and found key files 02 First Issue (auto) Open issue Title is clear and body has context 03 Join the Conversation Comment thread with @mention At least one substantive reply to the peer-simulation issue or a real buddy issue if access is provisioned 04 Branch Out Branch exists Any branch with any name exists 05 Make Your Mark (auto) Commit on branch File was edited and commit message is descriptive 06 First PR (auto) Open or merged PR PR has title + description + Closes #N 07 Merge Conflict (auto) Clean file in PR No conflict markers remain 08 Culture Comment or issue body with reflection Shows genuine engagement with governance files 09 Merge Day Merged PR At least one PR was reviewed and merged Day 2 Challenges (10-16) # Challenge Evidence Complete if... 10 Go Local (auto) Branch pushed from local clone Git log shows local commits 11 Day 2 PR PR from locally-pushed branch PR exists with description 12 Code Review Review comment on the peer-simulation PR or a real buddy PR if access is provisioned At least one specific, constructive comment 13 Copilot Evidence of Copilot interaction Shows both Copilot output AND student evaluation 14 Issue Template (auto) YAML file in .github/ISSUE_TEMPLATE/ Has name and description fields 15 Agents Exploration notes in issue or PR Examined at least one agent's instructions 16 Capstone PR, branch, issue, or contribution plan for Accessibility Agents, GLOW, or another meaningful repository, plus peer-simulation or real peer review evidence Has a clear mission, responsibilities, guardrails, and review-ready evidence Bonus Challenges (A-E) # Challenge Evidence Complete if... A Accessibility Audit Issue or PR with findings Identified at least 2 real accessibility issues B Mentor a Peer Thread showing guidance Helped another student resolve a challenge, or provided high-quality guidance on a peer-simulation issue if real peer access is unavailable C Cross-Repo Contribution PR to accessibility-agents or git-going repo PR submitted to a repo outside the learning room D Custom Workflow Workflow file or documentation Created or documented a reusable workflow E Documentation Champion Doc improvements in any repo Improved existing documentation with a merged PR Bonus challenges are entirely optional and do not affect core completion. Award bonus points for any genuine attempt. Completion Levels Level Day 1 + Day 2 participants Day 2 only participants Label Workshop Complete 7 of 9 (Day 1) + 5 of 7 (Day 2) 5 of 7 (Day 2) Participated fully Workshop Complete with Distinction 9 of 9 + 7 of 7 7 of 7 Completed all core challenges Workshop Complete with Honors 9 of 9 + 7 of 7 + 2 bonus 7 of 7 + 2 bonus Exceeded expectations Day-2-only participants are evaluated only on Day 2 challenges (10-16). They are not penalized for missing Day 1. Edge Cases Student used a different tool than described: Still counts. The learning objective is the skill, not the tool. Student's evidence is in the wrong place: Still counts. Redirect them for next time. Student helped others but did not finish their own work: Give credit for completed challenges. Helping others is valuable but does not substitute for personal evidence. Student worked ahead and completed Day 2 challenges on Day 1: Fine. Do not penalize initia" }, - { - "id": "classroom/HUMAN_TEST_MATRIX.html", - "title": "Human Test Matrix for Learning Room Challenges", - "url": "classroom/HUMAN_TEST_MATRIX.html", - "body": "Human Test Matrix for Learning Room Challenges Use this matrix before each cohort to verify that the Learning Room template behaves like a realistic collaborative GitHub project while still working inside private GitHub Classroom repositories. Required Test Repositories Create at least one disposable student repository from the current Community-Access/learning-room-template template. For full peer-access testing, create two disposable repositories and use two test student accounts. Minimum smoke test: learning-room-smoke-a Full collaboration test: learning-room-smoke-a learning-room-smoke-b Required Facilitator Setup After the student repository exists, run: scripts/classroom/Seed -LearningRoomChallenge .ps1 -Repository Community -Access /learning -room-smoke-a -Challenge 1 -Assignee test-student -a scripts/classroom/Seed -PeerSimulation .ps1 -Repository Community -Access /learning -room-smoke-a -StudentUsername test-student -a For Day 2-only testing, seed Challenge 10 instead: scripts/classroom/Seed -LearningRoomChallenge .ps1 -Repository Community -Access /learning -room-smoke-a -Challenge 10 -Assignee test-student -a scripts/classroom/Seed -PeerSimulation .ps1 -Repository Community -Access /learning -room-smoke-a -StudentUsername test-student -a What The Peer Simulation Creates Seed-PeerSimulation.ps1 creates realistic collaboration artifacts inside the student's private repo: Peer Simulation: Welcome Link Needs Context issue Peer Simulation: Review Request for Contribution Guidance issue Peer Simulation: Improve contribution guidance pull request docs/samples/peer-review-practice.md on branch peer-simulation/review-pr Students can use these artifacts whenever a challenge asks them to comment, react, review, compare, or practice collaboration. If facilitators separately provision real buddy access, students may use the real buddy repository instead. Day 1 Core Test Complete these steps as a test student. Challenge 1: Find Your Way Around Verify Challenge 1 issue exists. Complete the scavenger hunt. Comment evidence. Comment or react on the peer-simulation issue. Close Challenge 1. Verify Challenge 2 appears. Challenge 2: File Your First Issue Find a TODO in docs/welcome.md . Create a new issue with a clear title and description. Comment evidence on Challenge 2. Comment on the peer-simulation issue title/description. Close Challenge 2. Verify Challenge 3 appears. Challenge 3: Join the Conversation Comment on Peer Simulation: Welcome Link Needs Context . Include @gandalf-bot in the comment. Add a reaction. Verify Gandalf responds if issue-comment workflow permissions allow it. Close Challenge 3. Verify Challenge 4 appears. Challenge 4: Branch Out Create learn/test-student-a or equivalent feature branch. Compare with the peer-simulation PR branch name. Comment evidence. Close Challenge 4. Verify Challenge 5 appears. Challenge 5: Make Your Mark Edit the first TODO in docs/welcome.md on the feature branch. Commit with a descriptive message. Compare with the peer-simulation PR title or commit message. Comment evidence. Close Challenge 5. Verify Challenge 6 appears. Challenge 6: Open Your First Pull Request Open a PR from the feature branch to main . Include Closes #N for the Challenge 6 issue or the issue being solved. Verify Gandalf posts PR feedback. Comment on the peer-simulation PR. Close Challenge 6 when ready. Verify Challenge 7 appears. Challenge 7: Survive a Merge Conflict Run the facilitator conflict script after the student's PR exists: scripts/classroom/ Start-MergeConflictChallenge .ps1 -Repository Community -Access /learning -room-smoke-a -StudentBranch learn/ test-student -a Verify the student's PR reports a conflict. Resolve the conflict. Verify the Challenge 7 conflict-marker workflow succeeds. Close Challenge 7. Verify Challenge 8 appears. Challenge 8: The Culture Layer Read governance/community files. Use the peer-simulation issue for label/triage discussion. Comment reflection evidence. Close Challenge 8. Verify Challenge 9 appears. Challenge 9: Merge Day Verify the PR has been reviewed and can merge. Merge the PR or have the facilitator merge it. Leave wrap-up feedback on the peer-simulation issue or PR. Close Challenge 9. Day 2 Core Test Seed Challenge 10 if continuing from Day 1 did not naturally reach it. Challenge 10: Go Local Clone the repo locally. Create a branch. Edit, commit, and push. Verify the local commit workflow succeeds. Close Challenge 10. Verify Challenge 11 appears. Challenge 11: Open a Day 2 PR Open a PR from the locally pushed branch. Verify Gandalf feedback appears. Review the peer-simulation PR title and description. Close Challenge 11. Verify Challenge 12 appears. Challenge 12: Review Like a Pro Review the peer-simulation PR. Leave at least two specific comments if GitHub allows inline comments. Submit a review verdict if available. Comment evidence. Close Challenge 12. Verify Challenge 13 appears. Challenge 13: AI as Your Copilot Use Copilot to improve " - }, - { - "id": "classroom/index.html", - "title": "Workshop Deployment Guide", - "url": "classroom/index.html", - "body": "Workshop Deployment Guide Single, end-to-end guide for deploying a new Git Going with GitHub workshop cohort. Covers everything from creating the classroom through post-workshop teardown. This is the only deployment document you need. Before sharing invite links with students, complete the Go-Live QA Guide . It is the final release gate for content, workflows, Classroom setup, podcasts, accessibility, and human test coverage. If you need one practical execution script from registration through full student challenge completion (podcast work excluded), use admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md . Before creating assignments, sync and validate the latest template deployment using scripts/classroom/Prepare-LearningRoomTemplate.ps1 and scripts/classroom/Test-LearningRoomTemplate.ps1 . How the Workshop Works Each student gets their own private repository created by GitHub Classroom from the learning-room-template . Inside that repo, three automation systems guide the student through all 21 challenges without facilitator intervention: Gandalf (the PR Validation Bot) -- welcomes first-time contributors, validates PR structure, responds to @gandalf-bot help requests, and provides real-time feedback on every push Student Progression Bot -- creates the first challenge when triggered by a facilitator script, then creates the next challenge issue whenever a student closes the current challenge issue Autograders -- automated tests that verify objective evidence of challenge completion (branch exists, conflict markers removed, template file valid, agent file structured correctly) No shared student repository. Students do not clone the template or configure permissions. The facilitator's deployment work is creating the classroom and two assignments in the GitHub Classroom web UI, then running the seeding scripts after each student repo is created. Students only need a GitHub account. They do not need to create an organization, become members of Community-Access , or change GitHub Actions settings. Organization and repository workflow permissions are facilitator responsibilities. Architecture Community-Access/learning-room-template (template repo) | +--> GitHub Classroom creates one private repo per student | learning-room-student-a | learning-room-student-b | ... | +--> Each student repo contains: | Gandalf (pr-validation-bot.yml) -- PR feedback and help responses | Student Progression Bot -- Unlocks challenges sequentially | Autograders -- Validates specific challenges | Issue templates (16 core + 5 bonus) -- Challenge definitions | Feedback PR (created by Classroom) -- Facilitator async comments | +--> Student flow: | Accept invite --> repo created --> facilitator seeds Challenge 1 | --> complete challenge --> close issue --> next challenge unlocked | --> repeat through all challenges | +--> Capstone (Challenge 16): Student chooses Accessibility Agents, GLOW, or another meaningful project Opens a PR or prepares review-ready contribution evidence Two Participation Paths Path Who it is for Assignment Entry point Day 1 + Day 2 Participants starting from scratch Assignment 1 (Day 1) then Assignment 2 (Day 2) Day 1 Agenda Day 2 only Participants with GitHub fundamentals Assignment 2 only Day 2 Quick Start then Day 2 Agenda Day-2-only participants skip Assignment 1 entirely. They verify readiness using the Day 2 Quick Start self-assessment, then accept only the Day 2 invite link. What Is in This Directory File Purpose assignment-day1-you-belong-here.md Assignment description for Day 1 (paste into Classroom UI) assignment-day2-you-can-build-this.md Assignment description for Day 2 (paste into Classroom UI) grading-guide.md Facilitator rubric for all 21 challenges roster-template.csv Starter CSV for importing student roster student-progression.yml Reference copy of the progression bot workflow HUMAN_TEST_MATRIX.md End-to-end human walkthrough for all 16 core and 5 bonus challenges teardown-checklist.md Post-workshop cleanup steps ../GO-LIVE-QA-GUIDE.md Final release-readiness guide and checklist ../admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md Single operator runbook from registration to student completion (podcast excluded) Prerequisites Before starting, confirm the following: You have Owner or Admin access to the Community-Access GitHub organization Your facilitator GitHub account has a verified email address The Community-Access/learning-room-template repository exists and is public (or the classroom org has read access) The template repo has GitHub Actions enabled with Read and write permissions for GITHUB_TOKEN (Settings > Actions > General) -- Gandalf needs this to post comments "Allow GitHub Actions to create and approve pull requests" is checked in the template repo You have the student list (GitHub usernames required; real names optional) You have confirmed dates for Day 1 and Day 2 Role separation for testing Use separate accounts for facilitator and student testing. Keep your " - }, { "id": "classroom/assignment-day1-you-belong-here.html", "title": "Assignment 1: You Belong Here", @@ -2243,6 +2231,18 @@ "url": "classroom/teardown-checklist.html", "body": "Post-Workshop Teardown Checklist Use this checklist after each workshop cohort completes the course. Within 24 hours of Day 2 Export grades from GitHub Classroom (Classroom Settings, Download Grades) Verify all students have at least one merged PR Note any students who need follow-up (incomplete capstone, missing challenges) Send post-workshop survey link (see ANNOUNCEMENT.md for template) Within one week Review student feedback from surveys Move any private registration exports, accommodation notes, grade exports, or follow-up notes to Community-Access/git-going-student-success Archive the classroom (Classroom Settings, Archive) Close any remaining open issues across student Learning Room repositories (or leave them open if students want to continue practicing post-workshop) Merge or close any abandoned student PRs with a kind comment Update the student roster in the main repo if students should retain access for ongoing contribution Clean up student repositories GitHub Classroom creates one repository per student per assignment. After the course: Download any student work that should be preserved In Classroom settings, click "Delete all student repositories" (this is irreversible) Alternatively, keep the repositories for students who want to continue contributing Update facilitator notes Document any chapter sections that confused multiple students Note any technical issues encountered (e.g., Copilot activation problems, clone failures) File issues in the git-going-with-github repo for curriculum improvements Update the FACILITATOR.md with any new troubleshooting tips Prepare for next cohort Review and incorporate feedback from this cohort Update roster-template.csv with new student list Create a fresh classroom following README.md Test all invite links with a test account Authoritative Sources Use these official references when you need the current source of truth for facts in this chapter. GitHub Docs, home GitHub Changelog About Git GitHub flow About pull requests About issues Contributing to a project Section-Level Source Map Use this map to verify facts for each major section in this file. Within 24 hours of Day 2: GitHub Docs, home , GitHub Changelog , About Git , GitHub flow , About pull requests Within one week: GitHub Docs, home , GitHub Changelog , About Git , GitHub flow , About pull requests Clean up student repositories: GitHub Docs, home , GitHub Changelog , About Git , GitHub flow , About pull requests Update facilitator notes: GitHub Docs, home , GitHub Changelog , About Git , GitHub flow , About pull requests Prepare for next cohort: GitHub Docs, home , GitHub Changelog , About Git , GitHub flow , About pull requests" }, + { + "id": "classroom/HUMAN_TEST_MATRIX.html", + "title": "Human Test Matrix for Learning Room Challenges", + "url": "classroom/HUMAN_TEST_MATRIX.html", + "body": "Human Test Matrix for Learning Room Challenges Use this matrix before each cohort to verify that the Learning Room template behaves like a realistic collaborative GitHub project while still working inside private GitHub Classroom repositories. Required Test Repositories Create at least one disposable student repository from the current Community-Access/learning-room-template template. For full peer-access testing, create two disposable repositories and use two test student accounts. Minimum smoke test: learning-room-smoke-a Full collaboration test: learning-room-smoke-a learning-room-smoke-b Required Facilitator Setup The old scripts/classroom/ PowerShell seeding scripts were removed with GitHub Classroom. Seeding now runs through the Student Progression Bot workflow inside the student repository. After the student repository exists, open the repo's Actions tab, choose Student Progression Bot , select Run workflow , and set: start_challenge : 1 assignee : test-student-a For Day 2-only testing, set start_challenge to 10 instead. Equivalent CLI: gh workflow run student-progression.yml -R Community-Access/learning-room-smoke-a -f start_challenge=1 -f assignee=test-student-a What The Peer Simulation Creates The progression bot seeds realistic collaboration artifacts inside the student's private repo automatically whenever it creates a challenge issue (and repairs them if any are missing): Peer Simulation: Welcome Link Needs Context issue Peer Simulation: Review Request for Contribution Guidance issue Peer Simulation: Improve contribution guidance pull request docs/samples/peer-review-practice.md on branch peer-simulation/review-pr Students can use these artifacts whenever a challenge asks them to comment, react, review, compare, or practice collaboration. If facilitators separately provision real buddy access, students may use the real buddy repository instead. Day 1 Core Test Complete these steps as a test student. Challenge 1: Find Your Way Around Verify Challenge 1 issue exists. Complete the scavenger hunt. Comment evidence. Comment or react on the peer-simulation issue. Close Challenge 1. Verify Challenge 2 appears. Challenge 2: File Your First Issue Find a TODO in docs/welcome.md . Create a new issue with a clear title and description. Comment evidence on Challenge 2. Comment on the peer-simulation issue title/description. Close Challenge 2. Verify Challenge 3 appears. Challenge 3: Join the Conversation Comment on Peer Simulation: Welcome Link Needs Context . Include @gandalf-bot in the comment. Add a reaction. Verify Gandalf responds if issue-comment workflow permissions allow it. Close Challenge 3. Verify Challenge 4 appears. Challenge 4: Branch Out Create learn/test-student-a or equivalent feature branch. Compare with the peer-simulation PR branch name. Comment evidence. Close Challenge 4. Verify Challenge 5 appears. Challenge 5: Make Your Mark Edit the first TODO in docs/welcome.md on the feature branch. Commit with a descriptive message. Compare with the peer-simulation PR title or commit message. Comment evidence. Close Challenge 5. Verify Challenge 6 appears. Challenge 6: Open Your First Pull Request Open a PR from the feature branch to main . Include Closes #N for the Challenge 6 issue or the issue being solved. Verify Gandalf posts PR feedback. Comment on the peer-simulation PR. Close Challenge 6 when ready. Verify Challenge 7 appears. Challenge 7: Survive a Merge Conflict Run the facilitator conflict script after the student's PR exists: scripts/classroom/ Start-MergeConflictChallenge .ps1 -Repository Community -Access /learning -room-smoke-a -StudentBranch learn/ test-student -a Verify the student's PR reports a conflict. Resolve the conflict. Verify the Challenge 7 conflict-marker workflow succeeds. Close Challenge 7. Verify Challenge 8 appears. Challenge 8: The Culture Layer Read governance/community files. Use the peer-simulation issue for label/triage discussion. Comment reflection evidence. Close Challenge 8. Verify Challenge 9 appears. Challenge 9: Merge Day Verify the PR has been reviewed and can merge. Merge the PR or have the facilitator merge it. Leave wrap-up feedback on the peer-simulation issue or PR. Close Challenge 9. Day 2 Core Test Seed Challenge 10 if continuing from Day 1 did not naturally reach it. Challenge 10: Go Local Clone the repo locally. Create a branch. Edit, commit, and push. Verify the local commit workflow succeeds. Close Challenge 10. Verify Challenge 11 appears. Challenge 11: Open a Day 2 PR Open a PR from the locally pushed branch. Verify Gandalf feedback appears. Review the peer-simulation PR title and description. Close Challenge 11. Verify Challenge 12 appears. Challenge 12: Review Like a Pro Review the peer-simulation PR. Leave at least two specific comments if GitHub allows inline comments. Submit a review verdict if available. Comment evidence. Close Challenge 12. Verify Challenge 13 appears. Challenge 13: AI as Your Copilot Use Copilot to " + }, + { + "id": "classroom/index.html", + "title": "Workshop Deployment Guide", + "url": "classroom/index.html", + "body": "Workshop Deployment Guide Status note (2026-07): GitHub Classroom and the scripts/classroom/ PowerShell tooling described in this guide have been removed. Current cohorts use hybrid provisioning ( .github/scripts/provisioning/ , triggered by the provision-learning-rooms.yml workflow), and peer simulation artifacts are seeded automatically by the Student Progression Bot inside each learning room. Where this guide references a scripts/classroom/*.ps1 script, use the Student Progression Bot's Run workflow dispatch (inputs start_challenge and assignee ) instead. This guide is retained for the parts that are still accurate (challenge flow, bots, grading). Single, end-to-end guide for deploying a new Git Going with GitHub workshop cohort. Covers everything from creating the classroom through post-workshop teardown. This is the only deployment document you need. Before sharing invite links with students, complete the Go-Live QA Guide . It is the final release gate for content, workflows, Classroom setup, podcasts, accessibility, and human test coverage. If you need one practical execution script from registration through full student challenge completion (podcast work excluded), use admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md . Before creating assignments, sync and validate the latest template deployment using scripts/classroom/Prepare-LearningRoomTemplate.ps1 and scripts/classroom/Test-LearningRoomTemplate.ps1 . How the Workshop Works Each student gets their own private repository created by GitHub Classroom from the learning-room-template . Inside that repo, three automation systems guide the student through all 21 challenges without facilitator intervention: Gandalf (the PR Validation Bot) -- welcomes first-time contributors, validates PR structure, responds to @gandalf-bot help requests, and provides real-time feedback on every push Student Progression Bot -- creates the first challenge when triggered by a facilitator script, then creates the next challenge issue whenever a student closes the current challenge issue Autograders -- automated tests that verify objective evidence of challenge completion (branch exists, conflict markers removed, template file valid, agent file structured correctly) No shared student repository. Students do not clone the template or configure permissions. The facilitator's deployment work is creating the classroom and two assignments in the GitHub Classroom web UI, then running the seeding scripts after each student repo is created. Students only need a GitHub account. They do not need to create an organization, become members of Community-Access , or change GitHub Actions settings. Organization and repository workflow permissions are facilitator responsibilities. Architecture Community-Access/learning-room-template (template repo) | +--> GitHub Classroom creates one private repo per student | learning-room-student-a | learning-room-student-b | ... | +--> Each student repo contains: | Gandalf (pr-validation-bot.yml) -- PR feedback and help responses | Student Progression Bot -- Unlocks challenges sequentially | Autograders -- Validates specific challenges | Issue templates (16 core + 5 bonus) -- Challenge definitions | Feedback PR (created by Classroom) -- Facilitator async comments | +--> Student flow: | Accept invite --> repo created --> facilitator seeds Challenge 1 | --> complete challenge --> close issue --> next challenge unlocked | --> repeat through all challenges | +--> Capstone (Challenge 16): Student chooses Accessibility Agents, GLOW, or another meaningful project Opens a PR or prepares review-ready contribution evidence Two Participation Paths Path Who it is for Assignment Entry point Day 1 + Day 2 Participants starting from scratch Assignment 1 (Day 1) then Assignment 2 (Day 2) Day 1 Agenda Day 2 only Participants with GitHub fundamentals Assignment 2 only Day 2 Quick Start then Day 2 Agenda Day-2-only participants skip Assignment 1 entirely. They verify readiness using the Day 2 Quick Start self-assessment, then accept only the Day 2 invite link. What Is in This Directory File Purpose assignment-day1-you-belong-here.md Assignment description for Day 1 (paste into Classroom UI) assignment-day2-you-can-build-this.md Assignment description for Day 2 (paste into Classroom UI) grading-guide.md Facilitator rubric for all 21 challenges roster-template.csv Starter CSV for importing student roster student-progression.yml Reference copy of the progression bot workflow HUMAN_TEST_MATRIX.md End-to-end human walkthrough for all 16 core and 5 bonus challenges teardown-checklist.md Post-workshop cleanup steps ../GO-LIVE-QA-GUIDE.md Final release-readiness guide and checklist ../admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md Single operator runbook from registration to student completion (podcast excluded) Prerequisites Before starting, confirm the following: You have Owner or Admin access to the Community-Access GitHub organization Your facilitator GitHub acc" + }, { "id": "BATCH.html", "title": "Batch Command Reference", @@ -2303,12 +2303,6 @@ "url": "CONTRIBUTING.html", "body": "Table: Keyboard shortcut for focusing search in different screen readers Contributing to This Workshop Repository Thank you for helping improve this workshop. Whether you are a participant who found a typo, someone who wants to add a new exercise, or an educator adapting these materials for your own community - your contribution is meaningful and welcome. This guide covers contributing to this workshop learning repository . For contributing to Accessibility Agents itself (the project you work on during Day 2), see Accessibility Agents' CONTRIBUTING.md . Table of Contents Who This Is For What Kinds of Contributions Are Welcome Before You Start - Fork and Clone Contribution Workflow - Step by Step Writing and Style Guidelines Accessibility Requirements HTML Documentation Build System Screen Reader Guidance for Commands in This Document Submitting Your Pull Request What Happens After You Submit Questions and Discussion 1. Who This Is For Workshop participants: You have already completed the contribution workflow during the workshop. This repository is an excellent first contribution target for applying what you practiced. Educators and facilitators: You are welcome to fork the entire repository and adapt the materials for your own workshop program. Attribution is required under the CC BY 4.0 license - please include a credit line and link to the original repository. Accessibility practitioners: If you have domain expertise in a particular screen reader or assistive technology and notice something that is incorrect or incomplete, please open an issue or submit a correction. Your expertise is exactly what this documentation needs. People who find bugs: A broken link, a command that has stopped working, an exercise that cannot be completed - all of these are legitimate bugs. Open an issue the same way you would for any software project. 2. What Kinds of Contributions Are Welcome Documentation Improvements Corrections: Wrong keyboard shortcut, screen reader command that has changed, broken external link, outdated UI description Clarity: A step that was confusing, an assumption that left someone behind, a paragraph that should be two Gaps: A common question that the documentation does not answer, an exercise step that was skipped New content: An additional exercise, a section about a tool or workflow not yet covered, a translation Issues and Bug Reports A command in the workshop exercises that does not work as described A screen reader behavior that differs from what the documentation says A broken link or missing image An exercise that assumes knowledge introduced later in the workshop Workshop Materials New exercises that reinforce a concept Facilitator notes based on running a session Timing adjustments based on real session experience Alternative approaches for participants on different operating systems What We Are Not Looking For Right Now Rewriting the complete voice or structure of the workshop - if you have large-scale ideas, open a discussion first Adding content about tools or platforms not currently mentioned in the workshop Automated link-checking or content generation without human review 3. Before You Start - Fork and Clone You learned this workflow during the workshop. Here it is again as a reference. Account security Security: We strongly recommend enabling Two-Factor Authentication (2FA) on your GitHub account. If you cannot enable 2FA, add an SSH key or create a Personal Access Token (PAT) with repo scope before contributing. If you need help, contact the workshop organizers. Fork the Repository Navigate to the workshop repository on GitHub Activate the Fork button (top right of the repository page) Select your account as the fork destination Wait for the fork to complete - you will be redirected to your copy Screen reader users: NVDA / JAWS: Navigate by button ( B ) to find "Fork" VoiceOver: VO+Right Arrow to find "Fork" button, VO+Space to activate Clone Your Fork git clone https://github.com/[your-username]/[workshop-repo-name].git cd [workshop-repo-name] Add the Upstream Remote This keeps your fork synchronized with the original repository: git remote add upstream https://github.com/[original-owner]/[workshop-repo-name].git Verify both remotes are configured: git remote -v Expected output: origin https://github.com/ [ your-username ]/[workshop-repo-name].git (fetch) origin https://github.com/ [ your-username ]/[workshop-repo-name].git (push) upstream https://github.com/ [ original-owner ]/[workshop-repo-name].git (fetch) upstream https://github.com/ [ original-owner ]/[workshop-repo-name].git (push) 4. Contribution Workflow - Step by Step This is the same workflow you practiced during the workshop, applied to a real contribution. Step 1 - Sync with Upstream Always start from a current copy of the main branch: git checkout main git fetch upstream git merge upstream/main git push origin main Step 2 - Create a Focused Branch One issue or topic per branch. Branch names sho" }, - { - "id": "GO-LIVE-QA-GUIDE.html", - "title": "Git Going with GitHub Go-Live QA Guide", - "url": "GO-LIVE-QA-GUIDE.html", - "body": "Git Going with GitHub Go-Live QA Guide Use this guide before a cohort is opened to learners. It is the release gate for curriculum content, GitHub Classroom deployment, Learning Room automation, accessibility, and human test coverage. Podcast and LLM-generation QA is tracked here as non-blocking unless a podcast release is explicitly in scope. For end-to-end execution details, use admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md as the operator procedure. This guide is the release gate summary; the runbook is the required execution playbook. The goal is simple: a facilitator should be able to create a classroom, seed test repositories, complete every challenge path, validate every generated artifact, and know exactly what remains before students arrive. Important Note: Email and Notification Handling This curriculum does NOT depend on email notifications. Account verification emails (GitHub signup, email confirmation) are required by GitHub and are outside our control Notification emails (activity updates, mentions, assignments) are completely optional All challenges complete successfully using only GitHub's web notification inbox at github.com/notifications Students can disable email notifications in their GitHub settings after account setup—this will NOT break the workshop Chapter 10 (Notifications) focuses on managing the web notification inbox, not email delivery If a student's email delivery is problematic, delayed, or filtered by their ISP, they can still complete all challenges and exercises without any impact. Instructors should inform students that they can check github.com/notifications anytime instead of waiting for emails. Release Decision Do not mark a cohort ready until all required items in this section are complete. Automated tests pass locally. HTML documentation builds from the current Markdown sources. Learning Room source has been synced to Community-Access/learning-room-template and merged to main (or validated as no-change). Template smoke validation from Community-Access/learning-room-template succeeded before assignment publishing. Template freshness proof confirms smoke repo content matches latest merged template sync changes. Git diff whitespace check has no actual whitespace or conflict-marker errors. Registration deployment gate completed (issue form template, workflow enablement, required labels, and optional classroom automation settings). Registration comment flow is assignment-link based (no org invite dependency). Registration form smoke test passed on 2026-05-14 (submission accepted, redacted, labeled, and support routing confirmed). Support Hub is provisioned and publicly accessible at Community-Access/support . Registration confirmation and help pathways route support requests to Support Hub issues/discussions. Registration issue form template and labels are configured ( workshop-registration.yml , registration , duplicate , waitlist ). Smoke repo confirms all required workflow files are present (PR validation, content validation, progression, skills progression, and all autograder workflows: autograder-issue-filed.yml , autograder-branch-commit.yml , autograder-pr-link.yml , autograder-conflicts.yml , autograder-local-commit.yml , autograder-template.yml , autograder-capstone.yml , autograder-watchdog.yml ). Day 1 Classroom assignment has been created from the current Learning Room template. Day 2 Classroom assignment has been created from the current Learning Room template. A test student account accepted the Day 1 invite and received a private repository. A test student account accepted the Day 2 invite and received a private repository. A test student can reply ack , then close the enrollment issue as Challenge 0 and retain expected workflow state. A test student can reply day1-complete and receive Day 2 release comment. Challenge 1 can be seeded and completed. Challenge 10 can be seeded and completed. Gandalf posts PR feedback on a test pull request. Student Progression Bot creates the next challenge when a challenge issue is closed. Autograder workflows run inside the student repo and post pass/fail comments on the relevant issues and PRs. (Classroom UI test cases are intentionally not configured -- see admin/classroom/autograding-setup.md .) Peer simulation artifacts can be seeded and used for review practice. Human testers completed the Day 1, Day 2, bonus, accessibility, and content-review passes below. Challenge tracking log includes explicit status and evidence for Challenges 1-16 and Bonus A-E. Challenge reliability matrix includes happy path, failure path, and recovery evidence for each challenge family. Runbook Phase 8 required checklist is complete in admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md . Student recovery Level 2 restore test is completed and evidenced with branch and PR links. All in-scope automation workflows and facilitator scripts were validated with expected behavior and evidence. Local non-podcast readiness evidence is recorded in admin/qa-readiness . " - }, { "id": "README.html", "title": "GIT Going with GitHub", @@ -2339,12 +2333,6 @@ "url": "golden.html", "body": "golden.md The north star for GIT Going with GitHub (GLOW). This document defines what "golden" means for this project, names the single biggest risk to its future, and lays out a bold, dependable, accessible path to get there. It is a vision document and a decision record. When a choice is hard, return here. One sentence: Every blind and low vision learner who starts this workshop should reach a real, merged open source contribution through an experience so reliable, so accessible, and so quietly delightful that the technology disappears and only their growing confidence remains. Table of contents What golden means The existential risk: GitHub Classroom is going away Design principles that never bend Architecture options for life after Classroom The recommended path: GitHub-native core, Flask companion at the edges The decoupling contract: own your state The five quality pillars Failure modes and graceful recovery Phased roadmap Definition of golden: the release gate Guardrails and non-negotiables What golden means Golden is not "feature complete." Golden is a standard of care. A golden release of this workshop is: Dependable. A facilitator can open a cohort and trust that every link resolves, every workflow fires, every challenge can be completed, failed, and recovered. No surprises on go-live day. Accessible by construction. Not retrofitted. Every artifact, every automation message, every fallback page is authored to be read with or without a screen reader, navigated by keyboard alone, and understood without sight. Accessibility is the product, not a checkbox. Flexible. The learning experience survives a vendor sunset, an API change, a renamed button, or a student who arrives with a different tool than expected. The curriculum already teaches "tools change, exploration is the skill." The infrastructure must live that value too. Error free where it counts. Zero broken learner-facing paths. Automation either succeeds, or fails loudly to a human with a clear recovery action. Silent failure is the only unacceptable outcome. Magical and delightful. The small things: a welcome that uses the learner's name, a validation bot that congratulates instead of scolds, a recovery path that feels like a safety net rather than a punishment, an audio companion when screen reader fatigue sets in. Delight is the sum of a hundred respected details. If a change does not move the project toward all five at once, question it. The existential risk: GitHub Classroom is going away The entire Learning Room model currently assumes GitHub Classroom exists. Today the flow is: a student accepts a Classroom assignment link, Classroom clones a template repository into a private student repository, and a chain of GitHub Actions drives registration, Day 2 release, autograding, progression, and the instructor dashboard. See admin/GITHUB_CLASSROOM_ARCHITECTURE.md for the current production design. This is a single point of failure. If GitHub Classroom is deprecated, removed, or changes its assignment model, the workshop's onboarding spine breaks. The good news: most of the value does not actually live in Classroom. Classroom does exactly two things for us: Provisioning. It copies a template repository into a per-student private repository and grants access. Roster mapping. It associates a GitHub identity with a roster entry. Everything else that makes this workshop work already lives in places we control: the curriculum in docs/ , the automation in the Learning Room workflows ( learning-room/.github/workflows/ ), the autograders, the progression bot, the registration flow, and the support hub. Classroom is a thin provisioning layer, not the brain. The golden response is therefore not panic. It is deliberate decoupling : replace the two things Classroom does for us with infrastructure we own, keep everything else exactly where it is, and lose nothing the learner depends on. Design principles that never bend These are the constitution. Every architectural choice below is measured against them. Accessibility is non-negotiable. Any replacement for Classroom must be fully operable with NVDA, JAWS, and VoiceOver, by keyboard alone. A provisioning UI that a blind learner cannot use is not a candidate, no matter how convenient it is for facilitators. Prefer infrastructure the learner already trusts. GitHub itself is the safest home. A learner who can navigate github.com can already operate most of our flow. New surfaces add new accessibility risk and new failure modes. Own your state. Never again let a single vendor feature hold the cohort hostage. Roster, progress, and provisioning state must be reconstructable from data we control. Degrade gracefully, never silently. Every automated step has a documented manual fallback that a facilitator can run by hand. The automation is an accelerator, not a dependency. One arc, many tools. The curriculum is one journey from browser to github.dev to VS Code. The infrastructu" }, - { - "id": "work.html", - "title": "Work.md", - "url": "work.html", - "body": "Work.md Consolidated walkthrough generated from the challenge issue templates in learning-room/.github/ISSUE_TEMPLATE/ . Do not edit this file manually. Run npm run build:html (or node scripts/generate-work-md.js ) to regenerate. Core challenges Challenge 1: Find Your Way Around Source template: challenge-01-find-your-way.yml Chapters: Ch02: Understanding GitHub | Ch03: Navigating Repositories | Ch04: The Learning Room What you will do: Explore this learning-room repository like a scavenger hunt. You will navigate tabs, the file tree, read key files, and find landmarks. Step-by-step scavenger hunt Task 1: Count files in the root Make sure you are on the Code tab (click it at the top) Look at the file/folder list Count how many items are showing (stop before the first folder) Write down this number Task 2: Find an open issue Click the Issues tab Look for issues with a green Open label Click on one to read it Write down its title Task 3: Read welcome.md Click the Code tab Look for a folder named docs/ Click to open it Find welcome.md and click it Read the first paragraph (the opening sentence) Write down what it says Task 4: Find the repo description Go to the Code tab Look at the top-right area - you should see a text description under the repo name This is the "About" section Write down what it says Task 5: Read the README On the Code tab, scroll down to find README.md Click it to open Find the section that says "Who this workshop is for" Write down the answer Task 6: Check the About section On the Code tab, look at the right sidebar You should see a section labeled "About" with repo information Write down what you see there Your evidence (fill in when closing this issue): 1. I found ___ files in the root of the repository. 2. The open issue I found was titled "___". 3. The first paragraph of welcome.md says... 4. The repository description is... 5. The README says this workshop is for... 6. The About section shows... Peer simulation check After you submit your evidence, open the Peer Simulation: Welcome Link Needs Context issue in this repository and leave an encouraging comment or reaction. If your facilitator gave you access to a real buddy repository, you may use your buddy's issue instead. If you get stuck Symptom Try this I cannot find the tabs Look for a horizontal navigation bar below the repository name. Screen reader users: navigate by heading level 2 or use the landmark navigation. I cannot find docs/welcome.md On the Code tab, look for a folder called docs . Select it, then select welcome.md . I am not sure what counts as evidence Any description of what you found works. There are no wrong answers in a scavenger hunt. I finished but want to check my work View the reference solution Challenge 2: File Your First Issue Source template: challenge-02-first-issue.yml Chapter: Ch05: Working with Issues What you will do: Find a TODO comment in docs/welcome.md , then file an issue describing the problem with a clear title and description. Instructions Open docs/welcome.md and look for a line that contains TODO -- this marks something that needs fixing. Go to the Issues tab and select New issue . Write a clear, descriptive title (not just "Fix TODO"). In the description, use this required format: - What: what needs to change - Where: where the problem is (must include docs/welcome.md ) - Why: why the change matters - Mention the exact TODO text you found Required format (checked automatically) Use this structure in your issue description: What: Replace the placeholder TODO with real welcome text. Where: docs/welcome.md, intro section. Why: New contributors need clear context when they open the file. TODO found: TODO: Add a short workshop welcome paragraph. ```text #### What makes a good issue title? | Instead of this | Write this | |---|---| | Fix TODO | Fix missing workshop description in welcome.md | | Bug | welcome.md TODO placeholder needs real content | | Update file | Replace TODO in welcome.md intro section with actual welcome text | --- **Your evidence** (fill in when closing this issue): ```text Issue URL: https://github.com/... I found a TODO in docs/welcome.md that said... My issue title was... Peer simulation check Open the Peer Simulation: Welcome Link Needs Context issue and leave a comment: Is the title clear? Would you know what needs fixing just from reading the title? If your facilitator gave you access to a real buddy repository, you may review your buddy's issue instead. If you get stuck Symptom Try this I cannot find the TODO Open docs/welcome.md and use your browser's find feature (Ctrl+F or Cmd+F) to search for "TODO". I am not sure what to write in the description Describe the problem as if you are explaining it to someone who has never seen the file. The New issue button is not visible Make sure you are on the Issues tab. If issues are disabled, ask your facilitator. I finished but want to check my work View t" - }, { "id": "CLAUDE.html", "title": "CLAUDE.md", @@ -2374,5 +2362,17 @@ "title": "The Adventure Gate: Student Opt-In", "url": "REGISTER.html", "body": "The Adventure Gate: Student Opt-In Back to Home | Support Hub | Pre-Workshop Setup Guide Join the next GIT Going with GitHub cohort Welcome, traveler. I am your Grey Wizard Mentor at the gate, here to welcome you to your Git and GitHub adventure. Learn online from anywhere Remote learners follow the workshop as a fully online, self-paced experience . Every challenge, episode, and reference document is published on the public site, available to read or listen to at any time. You will work in your own GitHub learning room with mentors and automation agents supporting you through issues and discussions. No travel, no special software -- just a browser, a keyboard, and your assistive tech of choice. Begin at your own pace and open a discussion whenever you need a mentor. A magical welcome My role is simple: set expectations, light the path when Git gets foggy, and help you move from uncertain first steps to confident collaboration. In class, we travel through short quests, clear checkpoints, and practical support from mentors and automation agents. Beyond class, I remain with you through the Support Hub, progression bots, and challenge feedback so your learning continues after the workshop ends. You only need one path to begin. Status Open for student opt-in Current confirmed registrations Loading... Cost Free Form Single enrollment form with automated confirmation and guided next steps One path to begin Sign in to your GitHub account . Open the enrollment form in a new tab. Answer the five quick prompts. Submit the form and open the new issue page that appears. Stay on that issue page until the automation comment posts your learning room link and next steps. Reply ack , then close the enrollment issue as Challenge 0 . Begin the Adventure (opens in new tab) How to fill the form (wizard tips) Use this quick spellbook so your form is accepted on the first try: Full Name: enter the name you want facilitators to call you (example: Jane Doe ). Email Address: use the best address for workshop updates (example: jane.doe@example.com ). Experience dropdowns: pick the option that feels true today. There is no wrong level. Course goals: write 1 to 3 short sentences about what you want to learn. Final check: confirm everything looks right, then click Submit new issue once. Your GitHub username is detected automatically from the account that submits the issue. If your goals box is blank, try this starter line: I want to feel confident using Git and GitHub in real projects. If you do not receive an email notification, refresh your submitted issue page directly to see the latest automation comment. What happens automatically Duplicate submissions are handled automatically. Registration is currently unlimited. Enrollment submissions are processed and public issue bodies are redacted after automation runs. Your learning room repository is provisioned automatically after enrollment. Challenge progression automation picks up as you close issues and open pull requests. Enrollment issues stay open until the student replies ack and closes the issue as Challenge 0. Important note Registration issues are public because this repository is public. Need help? File a support issue Join Support Hub Discussions A Community Access initiative. Authoritative Sources Use these official references when you need the current source of truth for facts in this chapter. GitHub Docs, home GitHub Changelog GitHub Discussions docs GitHub Gists docs Section-Level Source Map Use this map to verify facts for each major section in this file. Join the next GIT Going with GitHub cohort: GitHub Docs, home , GitHub Changelog , GitHub Discussions docs , GitHub Gists docs , About Git A magical welcome: GitHub Docs, home , GitHub Changelog , GitHub Discussions docs , GitHub Gists docs One path to begin: GitHub Docs, home , GitHub Changelog , GitHub Discussions docs , GitHub Gists docs , Workflow syntax for GitHub Actions How to fill the form (wizard tips): GitHub Docs, home , GitHub Changelog , GitHub Discussions docs , GitHub Gists docs , Issue forms syntax for GitHub What happens automatically: GitHub Docs, home , GitHub Changelog , GitHub Discussions docs , GitHub Gists docs Important note: GitHub Docs, home , GitHub Changelog , GitHub Discussions docs , GitHub Gists docs Need help?: GitHub Docs, home , GitHub Changelog , GitHub Discussions docs , GitHub Gists docs" + }, + { + "id": "work.html", + "title": "Work.md", + "url": "work.html", + "body": "Work.md Consolidated walkthrough generated from the challenge issue templates in learning-room/.github/ISSUE_TEMPLATE/ . Do not edit this file manually. Run npm run build:html (or node scripts/generate-work-md.js ) to regenerate. Core challenges Challenge 1: Find Your Way Around Source template: challenge-01-find-your-way.yml Chapters: Ch02: Understanding GitHub | Ch03: Navigating Repositories | Ch04: The Learning Room What you will do: Explore this learning-room repository like a scavenger hunt. You will navigate tabs, the file tree, read key files, and find landmarks. Step-by-step scavenger hunt Task 1: Count files in the root Make sure you are on the Code tab (click it at the top) Look at the file/folder list Count how many items are showing (stop before the first folder) Write down this number Task 2: Find an open issue Click the Issues tab Look for issues with a green Open label Click on one to read it Write down its title Task 3: Read welcome.md Click the Code tab Look for a folder named docs/ Click to open it Find welcome.md and click it Read the first paragraph (the opening sentence) Write down what it says Task 4: Find the repo description Go to the Code tab Look at the top-right area - you should see a text description under the repo name This is the "About" section Write down what it says Task 5: Read the README On the Code tab, scroll down to find README.md Click it to open Find the section that says "Who this workshop is for" Write down the answer Task 6: Check the About section On the Code tab, look at the right sidebar You should see a section labeled "About" with repo information Write down what you see there Your evidence (fill in when closing this issue): 1. I found ___ files in the root of the repository. 2. The open issue I found was titled "___". 3. The first paragraph of welcome.md says... 4. The repository description is... 5. The README says this workshop is for... 6. The About section shows... Peer simulation check After you submit your evidence, open the Peer Simulation: Welcome Link Needs Context issue in this repository and leave an encouraging comment or reaction. If your facilitator gave you access to a real buddy repository, you may use your buddy's issue instead. If you get stuck Symptom Try this I cannot find the tabs Look for a horizontal navigation bar below the repository name. Screen reader users: navigate by heading level 2 or use the landmark navigation. I cannot find docs/welcome.md On the Code tab, look for a folder called docs . Select it, then select welcome.md . I am not sure what counts as evidence Any description of what you found works. There are no wrong answers in a scavenger hunt. I finished but want to check my work View the reference solution Challenge 2: File Your First Issue Source template: challenge-02-first-issue.yml Chapter: Ch05: Working with Issues What you will do: Find a TODO comment in docs/welcome.md , then file an issue describing the problem with a clear title and description. Instructions Open docs/welcome.md and look for a line that contains TODO -- this marks something that needs fixing. Go to the Issues tab and select New issue . Write a clear, descriptive title (not just "Fix TODO"). In the description, use this required format: - What: what needs to change - Where: where the problem is (must include docs/welcome.md ) - Why: why the change matters - Mention the exact TODO text you found Required format (checked automatically) Use this structure in your issue description: What: Replace the placeholder TODO with real welcome text. Where: docs/welcome.md, intro section. Why: New contributors need clear context when they open the file. TODO found: TODO: Add a short workshop welcome paragraph. ```text #### What makes a good issue title? | Instead of this | Write this | |---|---| | Fix TODO | Fix missing workshop description in welcome.md | | Bug | welcome.md TODO placeholder needs real content | | Update file | Replace TODO in welcome.md intro section with actual welcome text | --- **Your evidence** (fill in when closing this issue): ```text Issue URL: https://github.com/... I found a TODO in docs/welcome.md that said... My issue title was... Peer simulation check Open the Peer Simulation: Welcome Link Needs Context issue and leave a comment: Is the title clear? Would you know what needs fixing just from reading the title? If your facilitator gave you access to a real buddy repository, you may review your buddy's issue instead. If you get stuck Symptom Try this I cannot find the TODO Open docs/welcome.md and use your browser's find feature (Ctrl+F or Cmd+F) to search for "TODO". I am not sure what to write in the description Describe the problem as if you are explaining it to someone who has never seen the file. The New issue button is not visible Make sure you are on the Issues tab. If issues are disabled, ask your facilitator. I finished but want to check my work View t" + }, + { + "id": "GO-LIVE-QA-GUIDE.html", + "title": "Git Going with GitHub Go-Live QA Guide", + "url": "GO-LIVE-QA-GUIDE.html", + "body": "Git Going with GitHub Go-Live QA Guide Status note (2026-07): GitHub Classroom and the scripts/classroom/ PowerShell tooling were removed; provisioning is now the hybrid pipeline in .github/scripts/provisioning/ , and peer simulation seeding happens automatically via the Student Progression Bot in each learning room. Interpret scripts/classroom/*.ps1 steps below as the Student Progression Bot workflow dispatch (inputs start_challenge , assignee ). Use this guide before a cohort is opened to learners. It is the release gate for curriculum content, GitHub Classroom deployment, Learning Room automation, accessibility, and human test coverage. Podcast and LLM-generation QA is tracked here as non-blocking unless a podcast release is explicitly in scope. For end-to-end execution details, use admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md as the operator procedure. This guide is the release gate summary; the runbook is the required execution playbook. The goal is simple: a facilitator should be able to create a classroom, seed test repositories, complete every challenge path, validate every generated artifact, and know exactly what remains before students arrive. Important Note: Email and Notification Handling This curriculum does NOT depend on email notifications. Account verification emails (GitHub signup, email confirmation) are required by GitHub and are outside our control Notification emails (activity updates, mentions, assignments) are completely optional All challenges complete successfully using only GitHub's web notification inbox at github.com/notifications Students can disable email notifications in their GitHub settings after account setup—this will NOT break the workshop Chapter 10 (Notifications) focuses on managing the web notification inbox, not email delivery If a student's email delivery is problematic, delayed, or filtered by their ISP, they can still complete all challenges and exercises without any impact. Instructors should inform students that they can check github.com/notifications anytime instead of waiting for emails. Release Decision Do not mark a cohort ready until all required items in this section are complete. Automated tests pass locally. HTML documentation builds from the current Markdown sources. Learning Room source has been synced to Community-Access/learning-room-template and merged to main (or validated as no-change). Template smoke validation from Community-Access/learning-room-template succeeded before assignment publishing. Template freshness proof confirms smoke repo content matches latest merged template sync changes. Git diff whitespace check has no actual whitespace or conflict-marker errors. Registration deployment gate completed (issue form template, workflow enablement, required labels, and optional classroom automation settings). Registration comment flow is assignment-link based (no org invite dependency). Registration form smoke test passed on 2026-05-14 (submission accepted, redacted, labeled, and support routing confirmed). Support Hub is provisioned and publicly accessible at Community-Access/support . Registration confirmation and help pathways route support requests to Support Hub issues/discussions. Registration issue form template and labels are configured ( workshop-registration.yml , registration , duplicate , waitlist ). Smoke repo confirms all required workflow files are present (PR validation, content validation, progression, skills progression, and all autograder workflows: autograder-issue-filed.yml , autograder-branch-commit.yml , autograder-pr-link.yml , autograder-conflicts.yml , autograder-local-commit.yml , autograder-template.yml , autograder-capstone.yml , autograder-watchdog.yml ). Day 1 Classroom assignment has been created from the current Learning Room template. Day 2 Classroom assignment has been created from the current Learning Room template. A test student account accepted the Day 1 invite and received a private repository. A test student account accepted the Day 2 invite and received a private repository. A test student can reply ack , then close the enrollment issue as Challenge 0 and retain expected workflow state. A test student can reply day1-complete and receive Day 2 release comment. Challenge 1 can be seeded and completed. Challenge 10 can be seeded and completed. Gandalf posts PR feedback on a test pull request. Student Progression Bot creates the next challenge when a challenge issue is closed. Autograder workflows run inside the student repo and post pass/fail comments on the relevant issues and PRs. (Classroom UI test cases are intentionally not configured -- see admin/classroom/autograding-setup.md .) Peer simulation artifacts can be seeded and used for review practice. Human testers completed the Day 1, Day 2, bonus, accessibility, and content-review passes below. Challenge tracking log includes explicit status and evidence for Challenges 1-16 and Bonus A-E. Challenge reliability matrix includes happy path, failure path, " } ] diff --git a/scripts/build-html.js b/scripts/build-html.js index c4624073..606abe8f 100644 --- a/scripts/build-html.js +++ b/scripts/build-html.js @@ -968,7 +968,11 @@ function findMarkdownFiles(dir, fileList = []) { findMarkdownFiles(filePath, fileList); } } else if (file.endsWith('.md')) { - fileList.push(filePath); + // gold.md is a private maintainer log; keep it out of the public site. + const relative = path.relative(process.cwd(), filePath).replace(/\\/g, '/'); + if (relative !== 'gold.md') { + fileList.push(filePath); + } } }); diff --git a/scripts/validate-authoritative-sources.js b/scripts/validate-authoritative-sources.js index f8cb934c..f3b6b166 100644 --- a/scripts/validate-authoritative-sources.js +++ b/scripts/validate-authoritative-sources.js @@ -39,8 +39,8 @@ function includeContentFile(relPath) { if (excludedPrefixes.some(prefix => n.startsWith(prefix))) return false; - // Tooling instructions, not curriculum content. - const excludedRootFiles = ['CLAUDE.md']; + // Tooling instructions and maintainer logs, not curriculum content. + const excludedRootFiles = ['CLAUDE.md', 'gold.md']; if (excludedRootFiles.includes(n)) return false; if (n.startsWith('docs/')) return true;
Teaching chapter: Chapter 00: Pre-Workshop Setup