diff --git a/.github/scripts/__tests__/challenge-reliability-coverage.test.js b/.github/scripts/__tests__/challenge-reliability-coverage.test.js new file mode 100644 index 0000000..59770cc --- /dev/null +++ b/.github/scripts/__tests__/challenge-reliability-coverage.test.js @@ -0,0 +1,83 @@ +const test = require('node:test'); +const assert = require('node:assert/strict'); +const fs = require('node:fs'); +const path = require('node:path'); + +const repoRoot = path.resolve(__dirname, '../../../'); + +function read(relativePath) { + return fs.readFileSync(path.join(repoRoot, relativePath), 'utf8'); +} + +test('challenge issue templates inventory remains complete', () => { + const templateDir = path.join(repoRoot, 'learning-room/.github/ISSUE_TEMPLATE'); + const files = fs.readdirSync(templateDir).filter(name => name.endsWith('.yml')); + + const core = files.filter(name => /^challenge-\d{2}-.+\.yml$/.test(name)); + const bonus = files.filter(name => /^bonus-[a-e]-.+\.yml$/.test(name)); + + assert.equal(core.length, 16, 'Expected 16 core challenge templates'); + assert.equal(bonus.length, 5, 'Expected 5 bonus challenge templates'); + + const expectedCore = Array.from({ length: 16 }, (_, i) => String(i + 1).padStart(2, '0')); + const actualCore = core.map(name => name.match(/^challenge-(\d{2})-/)[1]).sort(); + assert.deepEqual(actualCore, expectedCore, 'Core challenge numbering should be 01..16'); + + const actualBonus = bonus.map(name => name.match(/^bonus-([a-e])-/)[1]).sort(); + assert.deepEqual(actualBonus, ['a', 'b', 'c', 'd', 'e'], 'Bonus challenge lettering should be a..e'); +}); + +test('runbook challenge tracking table includes all 1-16 plus bonus A-E rows', () => { + const runbook = read('admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md'); + + for (let i = 1; i <= 16; i += 1) { + assert.match( + runbook, + new RegExp(`\\|\\s*${i}\\s*\\|`), + `Runbook tracker missing Challenge ${i} row` + ); + } + + ['A', 'B', 'C', 'D', 'E'].forEach(letter => { + assert.match( + runbook, + new RegExp(`\\|\\s*Bonus\\s+${letter}\\s*\\|`, 'i'), + `Runbook tracker missing Bonus ${letter} row` + ); + }); +}); + +test('runbook contains required reliability variation categories', () => { + const runbook = read('admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md'); + + const categories = [ + 'Happy path completion', + 'Common student error path', + 'Recovery path after feedback', + 'Automation latency/idempotency behavior', + ]; + + categories.forEach(category => { + assert.match( + runbook, + new RegExp(category.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'i'), + `Runbook missing required variation category: ${category}` + ); + }); + + const requiredCrossCutting = [ + 'Bot comment delay greater than expected window', + 'Workflow rerun without creating duplicate progression issues', + 'Student posts evidence in wrong place then corrects it', + 'Autograder false-negative suspicion escalated and resolved', + 'Permission/access prompt encountered and resolved', + ]; + + requiredCrossCutting.forEach(item => { + assert.match( + runbook, + new RegExp(item.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'i'), + `Runbook missing cross-cutting failure mode: ${item}` + ); + }); +}); diff --git a/.github/scripts/__tests__/qa-readiness-gates.test.js b/.github/scripts/__tests__/qa-readiness-gates.test.js new file mode 100644 index 0000000..a1ae9fb --- /dev/null +++ b/.github/scripts/__tests__/qa-readiness-gates.test.js @@ -0,0 +1,66 @@ +const test = require('node:test'); +const assert = require('node:assert/strict'); +const fs = require('node:fs'); +const path = require('node:path'); + +const repoRoot = path.resolve(__dirname, '../../../'); + +function read(relativePath) { + return fs.readFileSync(path.join(repoRoot, relativePath), 'utf8'); +} + +test('E2E runbook includes hard no-go readiness gates', () => { + const content = read('admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md'); + + const requiredSnippets = [ + 'Critical Precondition Gates (No-Go if any fail)', + 'Issue form template `workshop-registration.yml` exists', + 'Required labels exist: `registration`, `duplicate`, `waitlist`', + 'Learning Room Template Deployment Gate', + 'Prove template freshness', + 'Challenge Reliability and Failure-Mode Coverage (Required)', + 'Student-visible expected state map (required cross-check)', + 'Student recovery and reset playbook (required)', + 'Cross-cutting failure modes (must be tested at least once)', + 'Challenge reliability/failure-mode coverage complete:', + ]; + + requiredSnippets.forEach(snippet => { + assert.match( + content, + new RegExp(snippet.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'i'), + `Runbook missing required gate text: ${snippet}` + ); + }); +}); + +test('Go-live release checklist contains required non-podcast readiness gates', () => { + const content = read('GO-LIVE-QA-GUIDE.md'); + + const requiredChecklistItems = [ + 'Registration issue form template and labels are configured', + 'Learning Room source has been synced to `Community-Access/learning-room-template`', + 'Template smoke validation from `Community-Access/learning-room-template` succeeded', + 'Template freshness proof confirms smoke repo content matches latest merged template sync changes', + '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', + 'All in-scope automation workflows and facilitator scripts were validated with expected behavior and evidence', + ]; + + requiredChecklistItems.forEach(item => { + assert.match( + content, + new RegExp(item.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'i'), + `Go-live checklist missing required item: ${item}` + ); + }); +}); + +test('recovery restore script exists and is discoverable in scripts/classroom', () => { + const scriptPath = path.join(repoRoot, 'scripts/classroom/Restore-LearningRoomFiles.ps1'); + assert.equal(fs.existsSync(scriptPath), true, 'Missing recovery restore script in scripts/classroom'); + + const content = fs.readFileSync(scriptPath, 'utf8'); + assert.match(content, /Profile\s*=\s*'core-day1'/i, 'Recovery script should provide default restore profile'); + assert.match(content, /OpenPullRequest/i, 'Recovery script should support opening a recovery pull request'); +}); diff --git a/.github/scripts/__tests__/registration-workflow-readiness.test.js b/.github/scripts/__tests__/registration-workflow-readiness.test.js new file mode 100644 index 0000000..2b097be --- /dev/null +++ b/.github/scripts/__tests__/registration-workflow-readiness.test.js @@ -0,0 +1,44 @@ +const test = require('node:test'); +const assert = require('node:assert/strict'); +const fs = require('node:fs'); +const path = require('node:path'); + +const repoRoot = path.resolve(__dirname, '../../../'); + +function read(relativePath) { + return fs.readFileSync(path.join(repoRoot, relativePath), 'utf8'); +} + +test('registration workflow contains required label and duplicate/waitlist flows', () => { + const workflow = read('.github/workflows/registration.yml'); + + const requiredSnippets = [ + "contains(github.event.issue.title, '[REGISTER]')", + "labels: ['duplicate']", + "labels: ['waitlist']", + "labels: ['registration']", + 'CLASSROOM_ORG_ADMIN_TOKEN', + 'CLASSROOM_DAY1_ASSIGNMENT_URL', + 'CLASSROOM_DAY2_ASSIGNMENT_URL', + 'createInvitation', + 'Upload CSV as artifact', + 'Sync Student Roster (No PII)', + ]; + + requiredSnippets.forEach(snippet => { + assert.match( + workflow, + new RegExp(snippet.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'i'), + `Registration workflow missing expected behavior marker: ${snippet}` + ); + }); +}); + +test('registration issue form template exists', () => { + const templatePath = path.join(repoRoot, '.github/ISSUE_TEMPLATE/workshop-registration.yml'); + assert.equal(fs.existsSync(templatePath), true, 'Missing workshop-registration.yml issue form template'); + + const content = fs.readFileSync(templatePath, 'utf8'); + assert.match(content, /name:\s*"?Workshop Registration/i, 'Registration template should have user-facing name'); + assert.match(content, /body:/i, 'Registration template should define issue form body'); +}); diff --git a/GO-LIVE-QA-GUIDE.md b/GO-LIVE-QA-GUIDE.md index 3a0a29c..16ceae6 100644 --- a/GO-LIVE-QA-GUIDE.md +++ b/GO-LIVE-QA-GUIDE.md @@ -2,6 +2,8 @@ Use this guide before a cohort is opened to learners. It is the release gate for curriculum content, GitHub Classroom deployment, Learning Room automation, podcast materials, accessibility, and human test coverage. +For end-to-end execution details, use [admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md](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. ## Release Decision @@ -13,6 +15,12 @@ Do not mark a cohort ready until all required items in this section are complete - [ ] Podcast catalog validation passes. - [ ] RSS feed validation passes for the current audio state. - [ ] 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 issue form template and labels are configured (`workshop-registration.yml`, `registration`, `duplicate`, `waitlist`). +- [ ] 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. +- [ ] Smoke repo confirms all required workflow files are present (PR validation, content validation, progression, skills progression, and all autograders). - [ ] 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. @@ -24,8 +32,22 @@ Do not mark a cohort ready until all required items in this section are complete - [ ] Autograding runs and reports results in GitHub Classroom. - [ ] 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](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](admin/qa-readiness/README.md). - [ ] All blocking findings have a fix, owner, or written release exception. +No-go conditions: + +- Any Blocker finding remains open. +- Any required runbook Phase 8 gate is incomplete without explicit release-owner exception. +- Student progression, PR validation, or required autograder behavior is not reproducible in a test student repository. +- Template freshness proof is missing or shows drift from the latest merged template sync. +- Required QA evidence links are missing for release-signoff claims. + ## Source Of Truth The following table lists each release artifact and the document that controls it. @@ -34,6 +56,7 @@ The following table lists each release artifact and the document that controls i |---|---| | Classroom deployment | [classroom/README.md](classroom/README.md) | | Classroom copy-paste setup pack | [admin/classroom/README.md](admin/classroom/README.md) | +| End-to-end operator runbook (registration to completion, podcast excluded) | [admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md](admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md) | | Human challenge walkthrough | [classroom/HUMAN_TEST_MATRIX.md](classroom/HUMAN_TEST_MATRIX.md) | | Facilitator operations | [admin/FACILITATOR_OPERATIONS.md](admin/FACILITATOR_OPERATIONS.md) | | Facilitator guide | [admin/FACILITATOR_GUIDE.md](admin/FACILITATOR_GUIDE.md) | @@ -75,6 +98,8 @@ Expected results: Record the command output summary in the release notes or QA issue. +Required evidence destination for local readiness: [admin/qa-readiness/UNIT-TEST-RESULTS-2026-05-08.md](admin/qa-readiness/UNIT-TEST-RESULTS-2026-05-08.md) or an equivalent dated report in the same folder. + ## Phase 2: Content Inventory Review Every content file must be reviewed before go-live. Use this checklist to assign coverage. diff --git a/admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md b/admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md new file mode 100644 index 0000000..4eb253c --- /dev/null +++ b/admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md @@ -0,0 +1,1339 @@ +# 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: + +1. Registration intake and validation. +2. GitHub Classroom deployment and assignment setup. +3. Test account acceptance and repository seeding. +4. Full student walkthrough of every challenge path. +5. 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 + +The following table lists the source files this runbook consolidates. + +| Area | Source file | +|---|---| +| Registration entry page | [REGISTER.md](../REGISTER.md) | +| Registration automation admin | [REGISTRATION-ADMIN.md](REGISTRATION-ADMIN.md) | +| Registration automation quickstart | [REGISTRATION-QUICKSTART.md](REGISTRATION-QUICKSTART.md) | +| Registration workflow logic | [.github/workflows/registration.yml](../.github/workflows/registration.yml) | +| Classroom deployment | [classroom/README.md](../classroom/README.md) | +| Assignment copy and autograding setup | [admin/classroom/README.md](classroom/README.md) | +| Human challenge walkthrough | [classroom/HUMAN_TEST_MATRIX.md](../classroom/HUMAN_TEST_MATRIX.md) | +| Challenge definitions | [docs/CHALLENGES.md](../docs/CHALLENGES.md) | +| Student starting path | [docs/get-going.md](../docs/get-going.md) | +| Grading criteria | [classroom/grading-guide.md](../classroom/grading-guide.md) | +| Release gate baseline | [GO-LIVE-QA-GUIDE.md](../GO-LIVE-QA-GUIDE.md) | + +## Required Accounts, Access, and Tools + +Complete this section before Phase 1. + +- Facilitator admin account with Owner or Admin access to the workshop organization and classroom organization. +- Dedicated non-admin test student account for acceptance and full challenge walkthrough. +- Access to [classroom.github.com](https://classroom.github.com). +- Access to repository settings for secrets and variables. +- Local clone of this repository with PowerShell available. +- GitHub CLI (`gh`) installed and authenticated for optional verification commands. + +### Critical Precondition Gates (No-Go if any fail) + +Complete all items below before any cohort launch actions. + +- [ ] Facilitator account can access both organizations involved in operations: + - [ ] `Community-Access` + - [ ] `Community-Access-Classroom` (or your classroom org) +- [ ] Facilitator account has verified email and can create/edit Classroom assignments. +- [ ] Dedicated non-admin test student account exists and can accept invites. +- [ ] `gh auth status` succeeds for facilitator account 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: + - [ ] Secret: `CLASSROOM_ORG_ADMIN_TOKEN` + - [ ] Variables: `CLASSROOM_ORG`, `CLASSROOM_DAY1_ASSIGNMENT_URL`, `CLASSROOM_DAY2_ASSIGNMENT_URL` +- [ ] Registration entry configuration exists and is valid: + - [ ] Issue form template `workshop-registration.yml` exists + - [ ] Required labels exist: `registration`, `duplicate`, `waitlist` +- [ ] Facilitator can open `classroom.github.com`, view target classroom org, and create assignments. + +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 + +1. Sign in as the facilitator account on github.com. +2. Open your profile menu, then Your organizations. +3. Confirm both organizations are visible and accessible: + - `Community-Access` + - `Community-Access-Classroom` (or your classroom org) +4. Open both org pages and confirm you can view repositories and settings areas you are expected to manage. +5. Optional CLI verification from repository root: + +```powershell +gh auth status -h github.com +gh repo view Community-Access/git-going-with-github +gh repo view Community-Access/learning-room-template +``` + +Why this matters: + +- All downstream setup fails if the facilitator identity is not correctly scoped. + +#### B. Configure registration automation key and variables + +Repository target: `Community-Access/git-going-with-github` + +1. Open repository Settings. +2. Open Secrets and variables, then Actions. +3. Open the Secrets tab and create or update secret: + - `CLASSROOM_ORG_ADMIN_TOKEN` +4. Open the Variables tab and create or update variables: + - `CLASSROOM_ORG` + - `CLASSROOM_DAY1_ASSIGNMENT_URL` + - `CLASSROOM_DAY2_ASSIGNMENT_URL` +5. Re-open each entry and confirm values have no leading or trailing spaces. +6. Run one registration test and confirm welcome comment contains assignment links when variables are set. + +Why this matters: + +- These values drive invite and assignment-link injection in registration responses. + +#### C. Configure template repository Actions permissions + +Repository target: `Community-Access/learning-room-template` + +1. Open repository Settings. +2. Open Actions, then General. +3. In Actions permissions, ensure Actions are enabled for the repository. +4. In Workflow permissions, set `GITHUB_TOKEN` to Read and write permissions. +5. Enable Allow GitHub Actions to create and approve pull requests. +6. Save changes. + +Why this matters: + +- Template automation and bot workflows require write-capable workflow token behavior. + +#### D. Confirm the repository is a template and hosted in Community-Access + +1. Open `Community-Access/learning-room-template`. +2. Open Settings, then General. +3. Confirm the repository is marked as a template repository. +4. Confirm default branch is `main`. + +Why this matters: + +- Classroom assignment creation depends on the repository being available as a template. + +#### E. Confirm the latest learning-room content is deployed to Community-Access template + +1. From repository root, run: + +```powershell +scripts/classroom/Prepare-LearningRoomTemplate.ps1 -Owner Community-Access -TemplateRepo learning-room-template +``` + +2. If the script reports changes, open and merge the generated sync pull request in `Community-Access/learning-room-template`. +3. If the script reports no changes, capture that output as evidence. +4. Verify merged PR (or no-change output) in QA notes. + +Why this matters: + +- This is the control point that proves Community-Access template content is current. + +#### F. Prove freshness from a new template-generated repository + +1. Run: + +```powershell +scripts/classroom/Test-LearningRoomTemplate.ps1 -Owner Community-Access -TemplateRepo learning-room-template -KeepSmokeRepo +``` + +2. Open the retained smoke repository. +3. Compare at least three files changed in the most recent template sync PR: + - one workflow file + - one issue template file + - one docs or script file +4. Confirm file content in smoke repo matches merged sync PR content. +5. Record comparison links and outcome in QA notes. + +Why this matters: + +- This proves newly created student repositories inherit the latest template state, not stale content. + +## Test Artifacts You Will Produce + +Collect the following evidence while running QA. + +- Screenshots of registration confirmation and waitlist behavior. +- Screenshot of Day 1 and Day 2 assignment configuration pages. +- Screenshot of Day 1 and Day 2 autograding test lists with correct counts. +- Link to Learning Room template sync PR (or explicit no-change output) before cohort launch. +- Evidence of template smoke validation from a repo created from `Community-Access/learning-room-template`. +- Links to test student Day 1 and Day 2 repositories. +- Screenshot or link proving Challenge 1 and Challenge 10 seeding succeeded. +- Links to PRs used to validate Aria and autograders. +- Evidence that progression creates the next issue after close. +- Completed chapter-by-chapter walkthrough tracker for all required docs files. +- Completed challenge tracker for Challenges 1 to 16 and Bonus A to E. +- Final sign-off checklist with pass/fail and owner notes. + +### Artifact Capture Procedure (Required) + +Use this procedure for every artifact in this section: + +1. Capture evidence immediately after the validation action completes. +2. Name the evidence with timestamp, phase, and short description. +3. Store URL-based evidence whenever possible; use screenshots when URL evidence is not available. +4. Add one-line context in QA notes describing what the evidence proves. +5. If evidence cannot be captured, log a defect and do not mark the related gate complete. + +Why this matters: + +- Sign-off quality depends on auditable evidence, not memory or verbal confirmation. + +## Runbook Execution Standard (Applies to Every Phase) + +Follow this standard across the entire runbook. + +1. Read the phase goal and pass criteria before performing actions. +2. Execute steps in order unless the runbook explicitly permits parallel execution. +3. After each major step, capture evidence and log result as Pass, Fail, or Blocked. +4. When a step fails, stop, execute troubleshooting guidance, and document outcome before continuing. +5. Do not mark a phase complete until all pass criteria are satisfied or formally risk-accepted. + +Why this matters: + +- Consistent execution prevents partial validation and improves handoff reliability between operators. + +## QA Validation Contract (What, Where, When, How, Expected Experience) + +Use this section as the operational standard for every phase. + +| What to validate | Where to validate | When expected | How to validate | Expected experience | +|---|---|---|---|---| +| Registration issue form opens with prefilled title | Public registration page and GitHub issue form | Immediately after selecting registration link | Open the registration form link from [REGISTER.md](../REGISTER.md) | Form opens with `[REGISTER]` prefilled and correct template fields | +| Registration labels and form template are present | Repository issues/labels and `.github/ISSUE_TEMPLATE` | Before first registration test | Verify labels and `workshop-registration.yml` exist | Registration workflow can label and process issues without setup errors | +| Registration confirmation behavior | Registration issue thread and Actions run for `registration.yml` | Within 1-3 minutes of issue submission | Submit test registration and inspect comment and labels | Welcome comment appears, `registration` label applied, no manual intervention required | +| Classroom invite link injection in confirmation | Same registration issue welcome comment | Same workflow run as registration confirmation | Confirm assignment URL variables are configured and inspect comment body | Day 1 and Day 2 links appear exactly once and are clickable | +| Duplicate registration handling | Duplicate registration issue | Within 1-3 minutes of duplicate submission | Submit second registration from same account | Issue auto-closed, `duplicate` label applied, link to original issue included | +| Waitlist behavior | Registration issue and labels | Within 1-3 minutes when capacity threshold is met | Validate in safe staging path or controlled test | Waitlist message appears and `waitlist` label applied | +| Classroom assignment creation | GitHub Classroom UI | During deployment phase before student testing | Configure Day 1 and Day 2 using source docs | Assignment fields match source of truth and are published | +| Student repo creation after acceptance | Classroom dashboard and student account repositories | 30-60 seconds after invite acceptance | Accept Day 1 and Day 2 invite URLs with test student account | Separate private repos are created and visible to facilitator and test student | +| Challenge seeding | Test student repository Issues tab | Within 30-90 seconds after seeding script run | Run seeding scripts and refresh Issues | Correct starting challenge appears and is assigned correctly | +| PR validation feedback (Aria) | Test student pull request comments and Actions | Within approximately 60 seconds after PR open/update | Open PR and push another commit | Single bot comment appears and updates rather than duplicating | +| Content validation feedback | Test student PR checks/comments and Actions | Within approximately 60 seconds after PR open/update | Include link/markdown/accessibility issues and inspect output | Required fixes and suggestions are clear and tied to changed files | +| Progression behavior | Test student Issues tab and Actions for student progression | After each challenge issue closure | Close challenge issue sequentially | Next challenge opens automatically with correct number/title | +| Skills progression behavior | PR merged event and resulting comment/workflow output | After PR merge | Merge test PR and inspect workflow output | Achievement/progress feedback posts without workflow failure | +| Autograder behavior | Classroom grading panel, PR checks, and Actions logs | On relevant challenge events | Trigger known pass and known fail for each autograded challenge | Failing scenarios are understandable and pass after correct fix | +| Chapter content consistency | Markdown files under [docs](../docs/README.md) | During curriculum review phase before sign-off | Execute full chapter and appendix checklist | All required docs reviewed and discrepancies logged | +| Challenge coverage completeness | Challenge tracking table in this runbook | During student journey execution | Fill all rows for 1-16 and A-E | No challenge row is left blank or untracked | + +## Reading Order for Operators + +Read these files in this exact order before executing the runbook. + +1. [REGISTRATION-QUICKSTART.md](REGISTRATION-QUICKSTART.md) +2. [REGISTRATION-ADMIN.md](REGISTRATION-ADMIN.md) +3. [classroom/README.md](../classroom/README.md) +4. [admin/classroom/autograding-setup.md](classroom/autograding-setup.md) +5. [classroom/HUMAN_TEST_MATRIX.md](../classroom/HUMAN_TEST_MATRIX.md) +6. [docs/CHALLENGES.md](../docs/CHALLENGES.md) + +Reading completion rule: + +1. Do not begin Phase 0 until all files above are opened and skimmed for current cohort context. +2. Log "reading complete" with timestamp in QA notes. + +Why this matters: + +- Most setup errors come from skipping source-of-truth docs before execution. + +## Pre-Flight Local Validation (Non-Podcast) + +Run these from repository root before live environment QA. + +```powershell +npm run test:automation +npm run build:html +git diff --check +``` + +Pass criteria: + +- Automation tests pass. +- HTML build completes. +- No unresolved conflict markers or whitespace check failures. + +### Local unit-test evidence requirements + +Record and publish local test evidence under [admin/qa-readiness](qa-readiness/README.md). + +Minimum evidence: + +- Test command used. +- Total tests, pass count, fail count. +- Any failing tests and remediation actions. +- Residual risk statement for hosted GitHub behavior not proven by local tests. + +Recommended report format: + +- [admin/qa-readiness/UNIT-TEST-RESULTS-2026-05-08.md](qa-readiness/UNIT-TEST-RESULTS-2026-05-08.md) + +No-go rule: + +- If local readiness tests fail, do not proceed to template deployment or classroom assignment setup. + +Execution procedure: + +1. Run commands in listed order from repository root. +2. Capture terminal output snippets for each command. +3. If any command fails, record failure cause and remediation attempt. +4. Re-run failed command after remediation and capture final outcome. + +Why this matters: + +- Pre-flight catches local defects before they become live Classroom failures. + +## Phase 0 - Registration System Deployment Gate (Admin Side) + +This phase is mandatory. Do not run registration QA tests until deployment/configuration is complete. + +### Step 0.1 Deploy registration issue form and workflow prerequisites + +Goal: ensure the registration intake system is deployed and configured for this course cohort. + +1. Confirm registration issue form template exists and is current: + - `.github/ISSUE_TEMPLATE/workshop-registration.yml` +2. Confirm registration workflow exists and is enabled: + - `.github/workflows/registration.yml` +3. Confirm required labels exist in repository: + - `registration` + - `duplicate` + - `waitlist` +4. Confirm repository Actions are enabled for this repository. + +Pass criteria: + +- Issue form template is present and selectable from "New issue". +- Registration workflow is enabled and visible in Actions. +- Required labels exist and are usable. + +### Step 0.2 Deploy optional registration-to-classroom automation settings + +Goal: enable automatic org invite and assignment-link injection in registration confirmation comments. + +1. In repository settings, configure secret: + - `CLASSROOM_ORG_ADMIN_TOKEN` +2. In repository settings, configure variables: + - `CLASSROOM_ORG` + - `CLASSROOM_DAY1_ASSIGNMENT_URL` + - `CLASSROOM_DAY2_ASSIGNMENT_URL` +3. Re-open each value and verify no leading or trailing spaces. + +Pass criteria: + +- Secret and variables are present with correct values. +- Configuration aligns with [REGISTRATION-ADMIN.md](REGISTRATION-ADMIN.md). + +### Step 0.3 Registration deployment smoke check + +Goal: validate deployed registration system can execute at least one full workflow run. + +1. Submit one test registration issue from a non-admin test account. +2. Confirm `Registration - Welcome & CSV Export` workflow completes. +3. Confirm welcome comment posts and `registration` label is applied. +4. If classroom automation is configured, confirm org invite status and assignment links appear. + +Pass criteria: + +- Registration workflow executes successfully end to end. +- Output comment/labels match deployed configuration. + +## Phase 1 - Registration System QA (Admin Side) + +### Step 1. Verify public registration entry path + +1. Open [REGISTER.md](../REGISTER.md) and confirm the registration link points to the issue form template with `workshop-registration.yml`. +2. Open the rendered registration page and activate the registration form link. +3. Confirm the issue form opens with `[REGISTER]` in the title. +4. Confirm the page communicates that registration issues are public. + +Pass criteria: +- Registration link opens correctly. +- Registration issue title is prefilled with `[REGISTER]`. +- Public visibility warning is present. + +### Step 2. Configure registration automation for classroom handoff + +Use [REGISTRATION-QUICKSTART.md](REGISTRATION-QUICKSTART.md) for fast entry and [REGISTRATION-ADMIN.md](REGISTRATION-ADMIN.md) for full details. + +1. Create or verify an admin token that can manage organization invitations. +2. In repository settings, add secret `CLASSROOM_ORG_ADMIN_TOKEN`. +3. In repository settings, set variables: + - `CLASSROOM_ORG` + - `CLASSROOM_DAY1_ASSIGNMENT_URL` + - `CLASSROOM_DAY2_ASSIGNMENT_URL` +4. Save and re-open each setting to confirm there are no leading or trailing spaces. + +Pass criteria: +- Secret exists and is scoped correctly. +- All 3 variables exist and values are correct. + +### Step 3. Execute registration happy-path test + +Use the non-admin test student account. + +1. Submit the registration issue form once. +2. Wait for `Registration - Welcome & CSV Export` workflow to complete. +3. Confirm the issue receives a welcome comment. +4. Confirm the welcome comment includes: + - Zoom registration information. + - Day 1 and Day 2 assignment links (if variables are set). + - Organization invitation status when classroom org automation is active. +5. Confirm `registration` label is applied. + +Pass criteria: +- Workflow succeeds. +- Comment content is complete and accurate. +- `registration` label exists on the issue. + +### Step 4. Execute duplicate and waitlist tests + +1. Submit a second registration issue from the same test account. +2. Confirm workflow marks the issue duplicate and closes it with guidance to the original issue. +3. For waitlist behavior, use a controlled test strategy: + - Preferred: run in a staging copy where capacity can be reached safely. + - Alternative: dry-run logic review from [.github/workflows/registration.yml](../.github/workflows/registration.yml) and verify conditions with maintainers. +4. Confirm waitlist message and `waitlist` label behavior in the chosen test environment. + +Pass criteria: +- Duplicate submission closes with duplicate guidance. +- Waitlist path and label behavior are validated. + +### Step 5. Verify CSV export and roster sync outputs + +1. Open the workflow run artifacts and download `registration-data`. +2. Confirm CSV includes expected columns and test user row. +3. Verify `.github/data/student-roster.json` is updated by workflow with non-PII operational fields. +4. Optionally trigger manual rebuild: + +```powershell +gh workflow run registration.yml -R community-access/git-going-with-github +``` + +Pass criteria: +- CSV artifact is present and parseable. +- Roster sync commit appears only when data changed. + +## Phase 2 - Learning Room Template Deployment Gate (Admin Side) + +This phase is mandatory. Do not create Classroom assignments until this gate is complete. + +### Step 6. Sync local Learning Room source into GitHub template repository + +Goal: ensure `Community-Access/learning-room-template` reflects the latest source from `learning-room/`. + +Run from repository root: + +```powershell +scripts/classroom/Prepare-LearningRoomTemplate.ps1 -Owner Community-Access -TemplateRepo learning-room-template +``` + +What to expect: + +1. Script verifies GitHub CLI auth. +2. Script ensures template repository settings (template mode and Actions permissions where allowed). +3. Script creates a sync branch and PR if changes exist. +4. If no changes exist, script reports no template changes to commit. + +Where to verify: + +- `Community-Access/learning-room-template` pull requests list. +- Template repository Actions/settings page. + +Pass criteria: + +- Template sync PR exists and is merged to `main`, or script reports no changes required. +- Template repository remains configured as a template repository. +- Template repository default branch is `main` and visible in repository settings. + +### Step 7. Validate published template with smoke repository + +Goal: prove that new repos created from the template include required workflows/templates and can trigger challenge progression. + +Run from repository root: + +```powershell +scripts/classroom/Test-LearningRoomTemplate.ps1 -Owner Community-Access -TemplateRepo learning-room-template +``` + +What to expect: + +1. Script creates a temporary private smoke repo from the template. +2. Script checks key files exist (student progression workflow, challenge template, progression script). +3. Script triggers Challenge 1 workflow dispatch. +4. Script deletes smoke repo unless `-KeepSmokeRepo` is specified. + +Where to verify: + +- Smoke repo creation/deletion in GitHub repos list. +- Workflow run history and issue creation in smoke repo when retained. + +Pass criteria: + +- Smoke repo creation succeeds from template. +- Required files exist in smoke repo. +- Challenge 1 workflow dispatch succeeds. +- Smoke repo validates workflow inventory: + - `pr-validation-bot.yml` + - `content-validation.yml` + - `student-progression.yml` + - `skills-progression.yml` + - `autograder-conflicts.yml` + - `autograder-local-commit.yml` + - `autograder-template.yml` + - `autograder-capstone.yml` + +### Step 8. Prove template freshness (latest release content is live) + +Goal: confirm that newly created repositories are generated from the latest deployed template content, not stale template state. + +1. Keep the smoke repository (`-KeepSmokeRepo`) or create another temporary smoke repo from template. +2. Open the merged template sync PR from Step 6. +3. Select at least 3 files changed in that PR, including at least: + - one workflow file, + - one issue template file, + - one docs or script file. +4. Verify those exact file changes are present in the smoke repository. +5. Record evidence links in your QA notes. + +Pass criteria: + +- Evidence shows smoke repo content matches the latest merged template sync changes. +- No stale-file mismatch is found. + +### Step 9. Optional comprehensive harness check + +For deeper verification, run: + +```powershell +scripts/classroom/Invoke-LearningRoomEndToEndTest.ps1 -SelfTest +``` + +Use full end-to-end mode when preparing major cohort launches or after significant automation updates. + +## Phase 3 - Classroom Deployment QA (Admin Side) + +### Step 10. Create classroom and import roster + +Use [classroom/README.md](../classroom/README.md) Steps 1 and 2. + +1. Create a new classroom in `Community-Access`. +2. Name it using `Git Going - [Cohort Name] - [Month Year]`. +3. Import roster using [classroom/roster-template.csv](../classroom/roster-template.csv). +4. Confirm test student appears in roster. + +Pass criteria: +- Classroom exists and is accessible to facilitators. +- Roster import succeeds with expected usernames. + +### Step 11. Create Day 1 assignment exactly + +Use [classroom/assignment-day1-you-belong-here.md](../classroom/assignment-day1-you-belong-here.md) and [admin/classroom/day1-assignment-copy-paste.md](classroom/day1-assignment-copy-paste.md). + +1. Create assignment with title `You Belong Here`. +2. Set type `Individual`. +3. Set visibility `Private`. +4. Select template `Community-Access/learning-room-template`. +5. Set `Grant students admin access` to `No`. +6. Set `Enable feedback pull requests` to `Yes`. +7. Paste Day 1 assignment description content. +8. Add Day 1 autograding entries from [admin/classroom/autograding-setup.md](classroom/autograding-setup.md). +9. Confirm Day 1 has 4 tests and total 50 points. +10. Save assignment and copy invite link. + +Pass criteria: +- Day 1 settings match source files exactly. +- Test count and points are correct. +- Feedback pull request is enabled and visible in assignment configuration. + +### Step 12. Create Day 2 assignment exactly + +Use [classroom/assignment-day2-you-can-build-this.md](../classroom/assignment-day2-you-can-build-this.md) and [admin/classroom/day2-assignment-copy-paste.md](classroom/day2-assignment-copy-paste.md). + +1. Create assignment with title `You Can Build This`. +2. Apply same base settings as Day 1 (individual, private, no admin access, feedback PR enabled). +3. Paste Day 2 assignment description content. +4. Add Day 2 autograding entries from [admin/classroom/autograding-setup.md](classroom/autograding-setup.md). +5. Confirm Day 2 has 6 tests and total 75 points. +6. Save assignment and copy invite link. + +Pass criteria: +- Day 2 settings match source files exactly. +- Test count and points are correct. +- Feedback pull request is enabled and visible in assignment configuration. + +### Step 13. Connect assignment URLs back to registration automation + +1. Add or update repository variables: + - `CLASSROOM_DAY1_ASSIGNMENT_URL` + - `CLASSROOM_DAY2_ASSIGNMENT_URL` +2. Re-run one registration test issue (new test account or controlled case). +3. Confirm both links appear in welcome comment. + +Pass criteria: +- Registration confirmation comment now includes both assignment URLs. + +## Phase 4 - Test Student Acceptance and Seeding (Bridge from Admin to Student) + +### Step 14. Test student accepts Day 1 and Day 2 invites + +Use the test student account. + +1. Open Day 1 invite URL. +2. Accept assignment and wait for repo creation. +3. Record Day 1 test repo URL. +4. Open Day 2 invite URL. +5. Accept assignment and wait for repo creation. +6. Record Day 2 test repo URL. + +Pass criteria: +- Two private repos are created and visible in classroom dashboard. + +### Step 15. Seed initial challenges and peer simulation + +Run commands from repository root. + +```powershell +scripts/classroom/Seed-LearningRoomChallenge.ps1 -Repository Community-Access-Classroom/learning-room-test-student-day1 -Challenge 1 -Assignee test-student +scripts/classroom/Seed-PeerSimulation.ps1 -Repository Community-Access-Classroom/learning-room-test-student-day1 -StudentUsername test-student +scripts/classroom/Seed-LearningRoomChallenge.ps1 -Repository Community-Access-Classroom/learning-room-test-student-day2 -Challenge 10 -Assignee test-student +scripts/classroom/Seed-PeerSimulation.ps1 -Repository Community-Access-Classroom/learning-room-test-student-day2 -StudentUsername test-student +``` + +If you use different repository names, replace values accordingly. + +Pass criteria: +- Challenge 1 appears in Day 1 repo. +- Challenge 10 appears in Day 2 repo. +- Peer simulation issues and PR exist in both repos. + +## Phase 5 - Curriculum Content QA (Walk every required chapter and appendix) + +This phase is required. Do not skip this phase even if challenge automation is passing. + +### Step 16. Execute full chapter and appendix walkthrough + +For each file listed below, open it and verify: + +1. Instructions are accurate for the current Classroom model. +2. Links resolve or are intentionally marked as practice targets. +3. Accessibility language is actionable and not visual-only. +4. Challenge references align with [docs/CHALLENGES.md](../docs/CHALLENGES.md). + +Use this per-file verification routine before checking each box: + +1. Open the file and read it once top to bottom without editing. +2. Re-read while validating the 4 checks above and capture any defects in your QA notes. +3. If no defect is found, mark the checkbox complete immediately. +4. If a defect is found, leave checkbox open until defect is logged with owner and due date. + +Why this matters: + +- This prevents "skim and check" behavior that misses broken learner paths. +- It ensures every completed checkbox represents a defensible QA review, not just a visual pass. + +Track completion using this checklist. + +Core learner docs: + +- [ ] [docs/get-going.md](../docs/get-going.md) +- [ ] [docs/course-guide.md](../docs/course-guide.md) +- [ ] [docs/student-onboarding.md](../docs/student-onboarding.md) +- [ ] [docs/CHALLENGES.md](../docs/CHALLENGES.md) + +Core chapters: + +- [ ] [docs/00-pre-workshop-setup.md](../docs/00-pre-workshop-setup.md) +- [ ] [docs/01-choose-your-tools.md](../docs/01-choose-your-tools.md) +- [ ] [docs/02-understanding-github.md](../docs/02-understanding-github.md) +- [ ] [docs/03-navigating-repositories.md](../docs/03-navigating-repositories.md) +- [ ] [docs/04-the-learning-room.md](../docs/04-the-learning-room.md) +- [ ] [docs/05-working-with-issues.md](../docs/05-working-with-issues.md) +- [ ] [docs/06-working-with-pull-requests.md](../docs/06-working-with-pull-requests.md) +- [ ] [docs/07-merge-conflicts.md](../docs/07-merge-conflicts.md) +- [ ] [docs/08-open-source-culture.md](../docs/08-open-source-culture.md) +- [ ] [docs/09-labels-milestones-projects.md](../docs/09-labels-milestones-projects.md) +- [ ] [docs/10-notifications-and-day-1-close.md](../docs/10-notifications-and-day-1-close.md) +- [ ] [docs/11-vscode-interface.md](../docs/11-vscode-interface.md) +- [ ] [docs/12-vscode-accessibility.md](../docs/12-vscode-accessibility.md) +- [ ] [docs/13-how-git-works.md](../docs/13-how-git-works.md) +- [ ] [docs/14-git-in-practice.md](../docs/14-git-in-practice.md) +- [ ] [docs/15-code-review.md](../docs/15-code-review.md) +- [ ] [docs/16-github-copilot.md](../docs/16-github-copilot.md) +- [ ] [docs/17-issue-templates.md](../docs/17-issue-templates.md) +- [ ] [docs/18-fork-and-contribute.md](../docs/18-fork-and-contribute.md) +- [ ] [docs/19-accessibility-agents.md](../docs/19-accessibility-agents.md) +- [ ] [docs/20-build-your-agent.md](../docs/20-build-your-agent.md) +- [ ] [docs/21-next-steps.md](../docs/21-next-steps.md) + +Appendices: + +- [ ] [docs/appendix-a-glossary.md](../docs/appendix-a-glossary.md) +- [ ] [docs/appendix-b-screen-reader-cheatsheet.md](../docs/appendix-b-screen-reader-cheatsheet.md) +- [ ] [docs/appendix-c-markdown-reference.md](../docs/appendix-c-markdown-reference.md) +- [ ] [docs/appendix-d-git-authentication.md](../docs/appendix-d-git-authentication.md) +- [ ] [docs/appendix-e-advanced-git.md](../docs/appendix-e-advanced-git.md) +- [ ] [docs/appendix-f-git-security.md](../docs/appendix-f-git-security.md) +- [ ] [docs/appendix-g-vscode-reference.md](../docs/appendix-g-vscode-reference.md) +- [ ] [docs/appendix-h-github-desktop.md](../docs/appendix-h-github-desktop.md) +- [ ] [docs/appendix-i-github-cli.md](../docs/appendix-i-github-cli.md) +- [ ] [docs/appendix-j-cloud-editors.md](../docs/appendix-j-cloud-editors.md) +- [ ] [docs/appendix-k-copilot-reference.md](../docs/appendix-k-copilot-reference.md) +- [ ] [docs/appendix-l-agents-reference.md](../docs/appendix-l-agents-reference.md) +- [ ] [docs/appendix-m-accessibility-standards.md](../docs/appendix-m-accessibility-standards.md) +- [ ] [docs/appendix-n-advanced-search.md](../docs/appendix-n-advanced-search.md) +- [ ] [docs/appendix-o-branch-protection.md](../docs/appendix-o-branch-protection.md) +- [ ] [docs/appendix-p-security-features.md](../docs/appendix-p-security-features.md) +- [ ] [docs/appendix-q-actions-workflows.md](../docs/appendix-q-actions-workflows.md) +- [ ] [docs/appendix-r-projects-deep-dive.md](../docs/appendix-r-projects-deep-dive.md) +- [ ] [docs/appendix-s-releases-tags-insights.md](../docs/appendix-s-releases-tags-insights.md) +- [ ] [docs/appendix-t-community-and-social.md](../docs/appendix-t-community-and-social.md) +- [ ] [docs/appendix-u-discussions-and-gists.md](../docs/appendix-u-discussions-and-gists.md) +- [ ] [docs/appendix-v-github-mobile.md](../docs/appendix-v-github-mobile.md) +- [ ] [docs/appendix-w-github-pages.md](../docs/appendix-w-github-pages.md) +- [ ] [docs/appendix-x-resources.md](../docs/appendix-x-resources.md) +- [ ] [docs/appendix-y-workshop-materials.md](../docs/appendix-y-workshop-materials.md) +- [ ] [docs/appendix-z-github-skills.md](../docs/appendix-z-github-skills.md) + +Phase 4 pass criteria: +- Every listed file has been reviewed and marked complete. +- Any doc defects are logged with owner and due date. + +### Step 17. Validate supporting content outside chapters + +Review the following content surfaces because they directly affect learner and facilitator experience. + +Use this verification routine for each section below (Root docs, Classroom docs, Learning Room automation docs): + +1. Open all files in the section and compare wording for the same workflow concepts. +2. Confirm setup steps, command names, and expected outcomes match current automation behavior. +3. Confirm links between docs resolve and point to the intended destination. +4. Mark each file checkbox only after you either confirm consistency or log a specific defect. + +Why this matters: + +- Learners and facilitators often use these supporting docs first; contradictions here cause avoidable support load. +- Cross-document consistency reduces failed setup attempts during live cohorts. + +- [ ] Root docs alignment: + - [ ] [README.md](../README.md) + - [ ] [BUILD.md](../BUILD.md) + - [ ] [REGISTER.md](../REGISTER.md) + - [ ] [CONTRIBUTING.md](../CONTRIBUTING.md) + - [ ] [SECURITY.md](../SECURITY.md) + - [ ] [REPOSITORY_SECURITY.md](../REPOSITORY_SECURITY.md) +- [ ] Classroom deployment docs: + - [ ] [classroom/README.md](../classroom/README.md) + - [ ] [classroom/HUMAN_TEST_MATRIX.md](../classroom/HUMAN_TEST_MATRIX.md) + - [ ] [classroom/grading-guide.md](../classroom/grading-guide.md) +- [ ] Learning Room automation docs: + - [ ] [learning-room/.github/STUDENT_GUIDE.md](../learning-room/.github/STUDENT_GUIDE.md) + - [ ] [learning-room/.github/FACILITATOR_GUIDE.md](../learning-room/.github/FACILITATOR_GUIDE.md) + - [ ] [learning-room/.github/SETUP_AND_MAINTENANCE.md](../learning-room/.github/SETUP_AND_MAINTENANCE.md) + - [ ] [learning-room/.github/DEPLOYMENT_VALIDATION.md](../learning-room/.github/DEPLOYMENT_VALIDATION.md) + +Pass criteria: + +- Supporting docs are consistent with chapter guidance and current automation behavior. +- Any cross-document contradictions are logged as defects. + +## Phase 6 - Student Journey QA (Walk every path as a student) + +Use [classroom/HUMAN_TEST_MATRIX.md](../classroom/HUMAN_TEST_MATRIX.md) as your execution baseline and record evidence for each challenge. + +Phase execution rule: + +1. Run student journey checks in challenge order unless explicitly validating a failure-mode branch. +2. For each challenge, capture issue URL, evidence comment URL, and workflow/check outcome. +3. Update the Challenge Tracking Log row immediately after each challenge completes. +4. If progression fails, stop sequence and resolve before moving to next challenge. + +Why this matters: + +- Ordered execution is required to validate progression automation and student experience continuity. + +### Student pre-read sequence before challenge execution + +Have the tester read in this order: + +1. [docs/get-going.md](../docs/get-going.md) +2. [docs/00-pre-workshop-setup.md](../docs/00-pre-workshop-setup.md) +3. [docs/04-the-learning-room.md](../docs/04-the-learning-room.md) +4. [docs/CHALLENGES.md](../docs/CHALLENGES.md) + +### Day 1 challenge walkthrough (Challenges 1 to 9) + +For each challenge issue, perform this pattern: + +1. Open challenge issue. +2. Complete required actions. +3. Post evidence comment. +4. Close issue. +5. Confirm next challenge issue appears. + +Challenge-specific checks: + +1. Challenge 1: verify orientation tasks and next challenge creation. +2. Challenge 2: create a clear issue from `docs/welcome.md` TODO. +3. Challenge 3: comment on peer simulation issue and include mention. +4. Challenge 4: create `learn/` branch. +5. Challenge 5: commit real content change with descriptive message. +6. Challenge 6: open PR with `Closes #N` and validate Aria response. +7. Challenge 7: run conflict seeding and resolve conflict markers. +8. Challenge 8: submit culture reflection evidence. +9. Challenge 9: merge PR and confirm linked issue closes. + +Run merge conflict setup when Challenge 7 is reached: + +```powershell +scripts/classroom/Start-MergeConflictChallenge.ps1 -Repository Community-Access-Classroom/learning-room-test-student-day1 -StudentBranch learn/test-student +``` + +Day 1 pass criteria: +- Progression works across all nine challenges. +- Aria feedback appears on test PRs. +- Challenge 7 conflict-marker checks fail before fix and pass after fix. + +### Day 2 challenge walkthrough (Challenges 10 to 16) + +Use the same five-step issue pattern for each challenge. + +Challenge-specific checks: + +1. Challenge 10: clone locally, branch, edit, commit, push, and verify local commit workflow. +2. Challenge 11: open PR from Day 2 local branch and verify feedback. +3. Challenge 12: complete structured review on peer simulation PR. +4. Challenge 13: capture Copilot suggestion and student judgment. +5. Challenge 14: create custom non-challenge issue template with required fields and verify workflow. +6. Challenge 15: inspect accessibility agents and capture findings. +7. Challenge 16: fork `Community-Access/accessibility-agents`, create agent file with frontmatter, responsibilities, and guardrails, then open cross-fork PR. + +Day 2 pass criteria: +- Progression works from 10 through 16. +- Autograders for 10, 14, and 16 provide useful pass/fail feedback. +- Capstone evidence is complete and reviewable. + +### Student-visible expected state map (required cross-check) + +Use this section to confirm what students should see, where they should see it, and what artifacts should exist after each stage. + +| Stage | Where student looks | What student should see | Expected artifacts | +|---|---|---|---| +| After assignment acceptance | Repository home and Issues tab | Private Learning Room repository created from template | Starter docs (`docs/welcome.md`, `docs/keyboard-shortcuts.md`, `docs/setup-guide.md`), workflows, issue templates | +| After initial seeding | Issues tab | Correct starting challenge issue appears (`Challenge 1` or `Challenge 10`) | Assigned challenge issue with clear instructions and evidence prompt | +| During Day 1 PR flow (Ch 4-6) | Branch selector, Pull requests, Actions | Student branch exists, PR open, bot feedback appears | Branch `learn/` or equivalent, PR with `Closes #N`, Aria validation comment | +| During merge conflict (Ch 7) | PR conversation/files, Checks tab | Conflict state visible, then resolved | Conflict markers present pre-fix, removed post-fix, conflict check transitions to pass | +| During Day 2 local flow (Ch 10-11) | Local clone and remote PR | Local commit/push reflected in PR and checks | Non-default-branch commit visible in history and checks | +| During template challenge (Ch 14) | File tree and PR checks | Custom template exists and passes required-field checks | New `.github/ISSUE_TEMPLATE/*.yml` file with `name` and `description` | +| During capstone (Ch 16) | Fork repo and capstone PR | Cross-fork contribution path works with required structure | Agent file with frontmatter, responsibilities, guardrails; PR evidence | +| Bonus path | Issue templates and evidence comments | Bonus templates are available and usable | Bonus issue evidence and status recorded in tracker | + +Pass criteria: + +- Student-visible state is confirmed at each stage above. +- Any mismatch between expected and observed student experience is logged as a defect. + +### Bonus path walkthrough (A to E) + +Bonus challenges are optional for students, but QA tracking is required for every bonus challenge. + +1. Open each bonus template. +2. Confirm instructions are understandable and actionable. +3. Track completion status for each bonus challenge A to E. +4. If a bonus challenge is not fully executed, record why and what validated the path. + +Pass criteria: +- All bonus challenges A to E have explicit status and notes. +- No bonus challenge is left untracked. + +### Challenge Tracking Log (Required) + +Use this tracker while executing Phase 5. Every row must be completed. + +Row completion standard: + +1. Status must be one of Pass, Fail, or Deferred. +2. Evidence link must point to issue, PR, workflow run, or equivalent proof. +3. Notes must include remediation or deferral rationale when status is not Pass. + +Why this matters: + +- Complete row data is required for defensible release decisions and post-run audits. + +| Challenge | Title | Status (Pass/Fail/Deferred) | Evidence link | Notes | +|---|---|---|---|---| +| 1 | Find Your Way Around | | | | +| 2 | File Your First Issue | | | | +| 3 | Join the Conversation | | | | +| 4 | Branch Out | | | | +| 5 | Make Your Mark | | | | +| 6 | Open Your First Pull Request | | | | +| 7 | Survive a Merge Conflict | | | | +| 8 | The Culture Layer | | | | +| 9 | Merge Day | | | | +| 10 | Go Local | | | | +| 11 | Open a Day 2 PR | | | | +| 12 | Review Like a Pro | | | | +| 13 | AI as Your Copilot | | | | +| 14 | Template Remix | | | | +| 15 | Meet the Agents | | | | +| 16 | Build Your Agent (Capstone) | | | | +| Bonus A | Improve an Existing Agent | | | | +| Bonus B | Document Your Journey | | | | +| Bonus C | Create a Group Challenge | | | | +| Bonus D | Notification Mastery | | | | +| Bonus E | Explore Git History Visually | | | | + +### Challenge Reliability and Failure-Mode Coverage (Required) + +Do not mark the challenge system reliable until this section is completed. + +#### Reliability test personas + +Run challenge validation with at least these personas: + +- Persona A: Day 1 + Day 2 student path (full path through 1-16). +- Persona B: Day-2-only student path (starts at Challenge 10). + +#### Required variation categories + +For each applicable challenge, test and document all categories below: + +1. Happy path completion. +2. Common student error path. +3. Recovery path after feedback. +4. Automation latency/idempotency behavior (reruns, duplicate events, delayed comments). + +#### Variation matrix by challenge family + +| Challenge family | Minimum failure/variation scenarios to test | Pass criteria | +|---|---|---| +| 1-3 orientation and issue flow | Missing evidence comment, evidence posted in wrong issue, issue closed without evidence, delayed bot response on mention | Student can recover without facilitator-only intervention; instructions remain clear | +| 4-6 branch/commit/PR flow | Wrong branch, commit to main, PR missing `Closes #N`, weak PR body, duplicate PR attempts | Bot/autograder guidance is actionable and student can fix to pass | +| 7 conflict flow | Conflict markers left in file, partial resolution, wrong file resolved, reintroducing markers on next commit | Fails when unresolved, passes after true resolution, feedback explains next step | +| 8-9 culture/merge flow | Reflection too vague, merge blocked by checks, PR approved but not mergeable, issue not auto-closing | Student can complete with clear guidance and accurate merge outcome | +| 10-11 local workflow | Local auth failure, push to wrong remote/branch, no new commit, PR from wrong base | Failure mode is discoverable and recoverable with provided guidance | +| 12 review workflow | Review left as comment only, no actionable feedback, review submitted on wrong PR | Challenge guidance clarifies expectations and evidence remains evaluable | +| 13 Copilot evidence | Missing prompt/evaluation details, copied output without judgment, evidence too shallow | Student can revise evidence and meet evaluation criteria | +| 14 template workflow | Template file wrong folder/name, missing `name`, missing `description`, invalid YAML | Autograder fails correctly and passes only after true fix | +| 15 agent exploration | Superficial exploration notes, wrong repo referenced, no evidence of actual inspection | Challenge remains completable with clear evidence requirements | +| 16 capstone | Missing frontmatter, missing responsibilities/guardrails, PR to wrong repo, incomplete cross-fork setup | Autograder/checklist catches gaps and student can recover to complete | +| Bonus A-E | Student starts bonus without prerequisites, partial completion, alternate evidence format | Each bonus has documented pass/fail/deferred outcome and rationale | + +#### Cross-cutting failure modes (must be tested at least once) + +- Bot comment delay greater than expected window. +- Workflow rerun without creating duplicate progression issues. +- Student posts evidence in wrong place then corrects it. +- Autograder false-negative suspicion escalated and resolved with facilitator override process. +- Permission/access prompt encountered and resolved (student and facilitator perspectives). + +#### Reliability gate pass criteria + +- Every challenge (1-16 and Bonus A-E) has at least one documented happy path and one documented variation/failure scenario. +- Recovery steps are validated, not assumed. +- No critical failure path requires hidden facilitator knowledge outside documented guidance. + +### Student recovery and reset playbook (required) + +If a student repository is corrupted, use this escalation path. + +#### Level 1: Student self-recovery (preferred) + +1. Re-open challenge instructions and compare against required target file. +2. Use PR diff to undo accidental changes. +3. Restore missing text from template references in challenge guidance. +4. Push a corrective commit and re-run checks. + +Use when: + +- Student changed only small sections in expected challenge files. + +#### Level 2: Facilitator-assisted file restore (safe branch+PR) + +Use the recovery script to restore baseline files from `Community-Access/learning-room-template` into a student repo on a recovery branch. + +Script: + +```powershell +scripts/classroom/Restore-LearningRoomFiles.ps1 -StudentRepository Community-Access-Classroom/learning-room-studentname -Profile core-day1 -OpenPullRequest +``` + +Profiles: + +- `core-day1` restores Day 1 starter docs. +- `core-day2` restores Day 2 sample docs. +- `automation-core` restores workflow files. +- `all-core` restores all above. +- `custom` restores explicit paths provided via `-Paths`. + +Use when: + +- A challenge file, sample file, or workflow file was accidentally overwritten or deleted. + +#### Level 3: Repository re-provision fallback + +If corruption is broad and recovery branch approach is not sufficient: + +1. Export evidence links needed for grading history. +2. Remove student assignment entry in Classroom (if policy allows). +3. Re-invite student to assignment to generate a fresh repository. +4. Re-seed appropriate challenge and peer simulation artifacts. +5. Document mapping from old repo to replacement repo in facilitator notes. + +Use when: + +- Student repo is not reasonably recoverable with targeted file restores. + +#### Recovery gate pass criteria + +- At least one Level 2 recovery test is completed in QA and documented. +- Facilitators can perform targeted restore without editing files manually in GitHub UI. +- Recovery actions preserve auditability through branch/PR evidence. + +## Phase 7 - Workflow and Automation Validation Matrix + +Use this matrix as your quick final automation check. + +Matrix execution procedure: + +1. Work row by row. +2. Trigger or locate the required event for each component. +3. Verify expected behavior in the stated location. +4. Record one evidence link per row. +5. Mark row complete only when observed behavior matches expected experience. + +Why this matters: + +- The matrix is the final integration proof that automation is functioning as designed. + +| Automation component | What to verify | Where to verify | Trigger timing | Expected experience | +|---|---|---|---|---| +| `registration.yml` welcome job | New registration handling | Registration issue comment + labels + Actions run | On issue open with `[REGISTER]` | Welcome comment posted, registration label applied, no manual intervention | +| `registration.yml` duplicate logic | Duplicate handling | Duplicate issue thread + labels + closed state | On second submission by same user | Duplicate message references original and issue auto-closes | +| `registration.yml` waitlist logic | Capacity full behavior | Registration issue comment + `waitlist` label | When threshold reached in controlled test | Waitlist message and label applied | +| `registration.yml` CSV export | Registration data artifact | Actions artifacts | Every registration run or manual dispatch | `registration-data` artifact is available and current | +| `registration.yml` roster sync | Non-PII roster update | [.github/data/student-roster.json](../.github/data/student-roster.json) and workflow commit | Every registration run or manual dispatch | Roster updates only when changed and no PII stored | +| `pr-validation-bot.yml` | PR structure and guidance checks | PR comments + Actions | PR open/edit/sync/review events | Validation comment appears and updates in place | +| `content-validation.yml` | Link/markdown/accessibility checks | PR checks/comments + Actions logs | PR open/edit/sync | Clear actionable findings tied to changed files | +| `student-progression.yml` | Challenge unlock sequence | Issues tab + Actions logs | Issue close and workflow dispatch | Next challenge issue appears with correct sequence | +| `skills-progression.yml` | Skill/achievement feedback | PR comments + Actions | PR merge | Achievement/progress feedback posts without failure | +| `autograder-conflicts.yml` | Conflict marker detection for Ch07 | Actions checks + PR status | PR open/edit for conflict scenario | Fails before fix, passes after marker removal | +| `autograder-local-commit.yml` | Local commit validation for Ch10 | Actions checks + PR/status output | Push/PR for Ch10 scenario | Detects non-default-branch commit | +| `autograder-template.yml` | Issue template validation for Ch14 | Actions checks + PR/status output | Template challenge workflow trigger | Fails missing fields, passes with `name` and `description` | +| `autograder-capstone.yml` | Agent structure validation for Ch16 | Actions checks + PR/status output | Capstone PR events | Validates frontmatter, responsibilities, and guardrails | +| `Seed-LearningRoomChallenge.ps1` | Challenge seed operation | Issues tab + workflow run history | On script execution | Target challenge appears and assignment is correct | +| `Seed-PeerSimulation.ps1` | Peer simulation artifacts | Issues + PR list + branch list | On script execution | Peer simulation issues and PR appear as expected | +| `Start-MergeConflictChallenge.ps1` | Merge conflict scenario creation | Student PR conflict state + checks | On script execution during Ch07 | Conflict becomes visible and resolvable | +| `Test-LearningRoomTemplate.ps1` | Template readiness scan | Script output + remediation notes | Before assignment publish and after updates | Reports readiness state and clear gaps | +| `Prepare-LearningRoomTemplate.ps1` | Template preparation operations | Script output + repository checks | Before go-live if prep needed | Required template prep completes without hidden failures | +| `Invoke-LearningRoomEndToEndTest.ps1` | Full-scripted QA helper path | Script output and referenced artifacts | Optional preflight or regression validation | End-to-end script executes expected checks | +| `Add-AutograderSafeguards.ps1` and `Fix-AutograderComments.ps1` | Autograder hardening utilities | Script output + workflow behavior | As needed during defects/fixes | Safeguards/comments behavior aligns with expected feedback quality | + +## Phase 8 - Final Sign-Off (Podcast-Excluded Release Gate) + +Use this checklist for final decision. For every item, complete the listed verification steps and record evidence before checking the box. + +- [ ] Registration intake path tested from public page to welcome comment. + Verification steps: + 1. Execute Phase 1 Step 1 and Step 3 with a test registration. + 2. Capture the public entry point, issue creation, and final welcome comment evidence. + 3. Confirm labels and comment content match expected behavior in the QA Validation Contract. + Why this matters: this proves the first learner touchpoint works end to end. + +- [ ] Registration duplicate handling validated. + Verification steps: + 1. Execute Phase 1 Step 4 duplicate scenario. + 2. Confirm duplicate issue closes automatically and references the original. + 3. Record issue links and labels in QA notes. + Why this matters: duplicate control prevents noisy intake and manual cleanup overhead. + +- [ ] Registration CSV and roster sync validated. + Verification steps: + 1. Execute Phase 1 Step 5. + 2. Download `registration-data` artifact and verify the expected test row. + 3. Confirm roster sync updates only when underlying data changes. + Why this matters: operations teams depend on accurate roster exports for cohort management. + +- [ ] Learning Room template sync to GitHub template repository validated. + Verification steps: + 1. Execute Phase 2 Step 6. + 2. Confirm sync PR merged (or no-change outcome) and template repo settings remain correct. + 3. Record PR link or no-change script output. + Why this matters: stale template state breaks downstream assignments even when source repo is correct. + +- [ ] Template smoke repository validation completed from latest template state. + Verification steps: + 1. Execute Phase 2 Step 7. + 2. Confirm smoke repo creation, required file inventory, and seed dispatch behavior. + 3. Record script output and retained evidence links. + Why this matters: this is the fastest proof that template consumers get runnable automation. + +- [ ] Template freshness proof completed against latest merged sync PR. + Verification steps: + 1. Execute Phase 2 Step 8. + 2. Compare at least three changed files from sync PR to smoke repo content. + 3. Log exact file comparisons in QA notes. + Why this matters: confirms new cohorts are not launched from outdated template snapshots. + +- [ ] Day 1 assignment configured and validated. + Verification steps: + 1. Execute Phase 3 Step 11. + 2. Verify assignment settings, description, autograder count, and points. + 3. Store screenshot of final assignment configuration page. + Why this matters: Day 1 misconfiguration creates immediate learner friction and grading drift. + +- [ ] Day 2 assignment configured and validated. + Verification steps: + 1. Execute Phase 3 Step 12. + 2. Verify assignment settings, description, autograder count, and points. + 3. Store screenshot of final assignment configuration page. + Why this matters: Day 2 challenge flow and capstone checks depend on exact assignment setup. + +- [ ] Registration form template and required labels validated. + Verification steps: + 1. Execute Phase 0 Step 0.1 and re-check before sign-off. + 2. Confirm `workshop-registration.yml` is current and selectable. + 3. Confirm labels `registration`, `duplicate`, and `waitlist` exist and are active. + Why this matters: the registration workflow cannot route correctly without these baseline objects. + +- [ ] Test student accepted both assignments and repos created. + Verification steps: + 1. Execute Phase 4 Step 14. + 2. Confirm two private repos are created for Day 1 and Day 2. + 3. Record both repository URLs in completion notes. + Why this matters: acceptance and repo provisioning are required before challenge QA can begin. + +- [ ] Full chapter and appendix walkthrough completed and tracked. + Verification steps: + 1. Execute Phase 5 Step 16 using the per-file verification routine. + 2. Ensure every required chapter and appendix checkbox is either complete or tied to a logged defect. + 3. Confirm no file in the required list is left unreviewed. + Why this matters: curriculum defects can invalidate otherwise healthy automation. + +- [ ] Supporting non-chapter content walkthrough completed and tracked. + Verification steps: + 1. Execute Phase 5 Step 17 using the section verification routine. + 2. Resolve or log all cross-document inconsistencies. + 3. Confirm all supporting-doc checkboxes are complete or defect-linked. + Why this matters: learners rely on these docs during setup and troubleshooting. + +- [ ] Challenge 1 and Challenge 10 seeding validated. + Verification steps: + 1. Execute Phase 4 Step 15. + 2. Confirm seeded issues appear in Day 1 and Day 2 test repos. + 3. Capture issue links for both seeded starting points. + Why this matters: seeding failures block both student journey entry paths. + +- [ ] Full Day 1 student path (1 to 9) completed. + Verification steps: + 1. Execute Phase 6 Day 1 walkthrough across Challenges 1-9. + 2. Confirm progression behavior after each issue closure. + 3. Fill Day 1 rows in Challenge Tracking Log with evidence links. + Why this matters: Day 1 is the foundational workflow and must be dependable for all learners. + +- [ ] Full Day 2 student path (10 to 16) completed. + Verification steps: + 1. Execute Phase 6 Day 2 walkthrough across Challenges 10-16. + 2. Confirm Day 2 autograder behavior for 10, 14, and 16. + 3. Fill Day 2 rows in Challenge Tracking Log with evidence links. + Why this matters: Day 2 validates local workflow, review quality, and capstone readiness. + +- [ ] All bonus challenges A to E tracked with status and evidence or deferral reason. + Verification steps: + 1. Execute Phase 6 Bonus path walkthrough. + 2. Mark each bonus row Pass, Fail, or Deferred with rationale. + 3. Attach evidence link or deferral reason for all five bonus items. + Why this matters: optional learner paths still require QA accountability. + +- [ ] Challenge reliability and failure-mode coverage completed for all challenge families. + Verification steps: + 1. Execute the full Challenge Reliability and Failure-Mode Coverage section. + 2. Validate at least one happy path and one variation path per challenge family. + 3. Confirm recovery behavior is tested, not assumed. + Why this matters: production reliability is defined by recovery from failure paths, not only happy-path success. + +- [ ] Student-visible expected state map was verified at each stage. + Verification steps: + 1. Execute the Student-visible expected state map cross-check. + 2. Compare observed state to each stage row in the table. + 3. Log any mismatch as a defect before sign-off. + Why this matters: this verifies the learner experience directly, not just backend workflow success. + +- [ ] Recovery/reset playbook validated with at least one Level 2 restore test. + Verification steps: + 1. Execute Student recovery and reset playbook Level 2 flow. + 2. Confirm restored files are proposed through branch and PR evidence. + 3. Record restore test repository, branch, and PR links. + Why this matters: facilitators need a proven restoration path during live delivery incidents. + +- [ ] Aria, progression, and autograder workflows validated with evidence. + Verification steps: + 1. Execute checks in the Workflow and Automation Validation Matrix for `pr-validation-bot.yml`, `student-progression.yml`, and all autograder workflows. + 2. Capture one pass and one actionable-fail evidence sample where applicable. + 3. Confirm feedback is clear enough for student self-recovery. + Why this matters: these workflows are the core automated coaching and grading systems. + +- [ ] Open defects documented with owner and due date. + Verification steps: + 1. Review QA notes for all unresolved findings. + 2. Ensure each defect has severity, owner, and due date. + 3. Confirm blocker defects are explicitly marked for release decision. + Why this matters: unresolved defects without ownership are operational risk hidden as "known issues." + +- [ ] Release owner signs go or no-go decision. + Verification steps: + 1. Confirm all required checklist items above are complete or have explicit risk acceptance. + 2. Populate Completion Output Template with final links and outcomes. + 3. Capture release owner decision (Go or No-Go) with approver name and date. + Why this matters: formal accountability prevents ambiguous launch decisions. + +## Troubleshooting and Rollback Quick Actions + +Use this section when a blocker appears during QA. + +1. Registration invite automation issue: + - Step 1: Confirm `CLASSROOM_ORG_ADMIN_TOKEN` and `CLASSROOM_ORG` values are present and correctly scoped. + - Step 2: If automation is still failing, disable org invite automation by clearing `CLASSROOM_ORG`. + - Step 3: Continue registration flow with manual classroom invite process. + - Verify: registration workflow still posts welcome response and assignment links as configured. + +2. Seeding failure: + - Step 1: Re-run seeding script with explicit repository slug and assignee. + - Step 2: Confirm target repo exists and Actions are enabled. + - Step 3: Confirm template workflow inventory includes seeding dependencies. + - Verify: expected challenge issue appears and is assigned correctly. + +3. Progression not creating next issue: + - Step 1: Confirm current challenge issue was closed, not left open with comment only. + - Step 2: Confirm `student-progression.yml` exists in target repository and has successful run history. + - Step 3: Re-dispatch progression workflow if needed. + - Verify: next challenge issue appears with correct numbering. + +4. Autograder mismatch: + - Step 1: Re-check exact autograder command/settings definitions in [admin/classroom/autograding-setup.md](classroom/autograding-setup.md). + - Step 2: Trigger known-fail and known-pass scenarios for the affected autograder. + - Step 3: Compare observed output with expected rubric behavior. + - Verify: fail messages are actionable and pass state is reachable with correct student behavior. + +Escalation rule: + +1. If blocker persists after one remediation cycle, log defect with owner and ETA. +2. Continue with unaffected phases only when blocker impact is clearly isolated. + +Why this matters: + +- Fast, repeatable recovery protects cohort timelines and prevents hidden release risk. + +## Completion Output Template (Copy into QA Issue) + +Before publishing the completion output: + +1. Confirm all required Phase 8 checklist items are complete or explicitly risk-accepted. +2. Ensure every section below includes links, not placeholders. +3. Attach defect list with owner and due date for any unresolved findings. +4. Capture final approver and decision timestamp. + +Why this matters: + +- This output is the release audit record and must be independently reviewable. + +```text +Runbook Version: admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md +Date: +QA Owner: +Facilitator Account: +Test Student Account: + +Registration QA: +- Happy path: +- Duplicate path: +- Waitlist path: +- CSV export: +- Roster sync: + +Classroom QA: +- Day 1 assignment URL: +- Day 2 assignment URL: +- Day 1 repo URL: +- Day 2 repo URL: + +Challenge QA: +- Chapter walkthrough complete (00-21 + Appendix A-Z): +- Supporting non-chapter content walkthrough complete: +- Day 1 complete (1-9): +- Day 2 complete (10-16): +- Challenge reliability/failure-mode coverage complete: +- Student-visible expected state map verified: +- Recovery Level 2 restore test completed: +- Bonus A status: +- Bonus B status: +- Bonus C status: +- Bonus D status: +- Bonus E status: + +Automation QA: +- Registration workflow: +- Registration form/label setup: +- Aria: +- Content validation: +- Progression: +- Skills progression: +- Autograders: +- Seeding scripts: + +Open Defects: +- [ID] Severity | Owner | ETA + +Release Decision: +- Go / No-Go +- Approver: +``` + +## What This Runbook Replaces + +This runbook is the operator-facing execution path that unifies registration, deployment, and end-to-end challenge QA. + +It does not replace source documents. It sequences them into one practical checklist so a single facilitator can execute and validate the full system without context switching across multiple folders. \ No newline at end of file diff --git a/admin/README.md b/admin/README.md index 3ca6e5e..a39e896 100644 --- a/admin/README.md +++ b/admin/README.md @@ -14,6 +14,7 @@ This folder contains all administrative and facilitator documentation for runnin - **[FACILITATOR_OPERATIONS.md](FACILITATOR_OPERATIONS.md)** - Hour-by-hour procedures during workshop - **[FACILITATOR_CLASSROOM_TROUBLESHOOTING.md](FACILITATOR_CLASSROOM_TROUBLESHOOTING.md)** - Problem-solving guide - **[../GO-LIVE-QA-GUIDE.md](../GO-LIVE-QA-GUIDE.md)** - Final release-readiness guide and end-to-end test checklist +- **[LEARNING-ROOM-E2E-QA-RUNBOOK.md](LEARNING-ROOM-E2E-QA-RUNBOOK.md)** - Single step-by-step QA runbook from registration to full student completion (podcast excluded) ### Supporting Guides - **[FACILITATOR_CHALLENGES.md](FACILITATOR_CHALLENGES.md)** - Managing the challenge system @@ -46,6 +47,8 @@ This folder contains all administrative and facilitator documentation for runnin - **[ACCESSIBILITY_TESTING.md](ACCESSIBILITY_TESTING.md)** - Testing workshop for accessibility - **[VALIDATION_AUDIT.md](VALIDATION_AUDIT.md)** - Validating everything works - **[classroom/README.md](classroom/README.md)** - Copy-paste classroom setup pack (assignments, autograding, seeding) +- **[LEARNING-ROOM-E2E-QA-RUNBOOK.md](LEARNING-ROOM-E2E-QA-RUNBOOK.md)** - Full registration-through-challenges QA execution path for one operator +- **[qa-readiness/README.md](qa-readiness/README.md)** - Local unit-test readiness evidence pack (non-podcast) - **[../GO-LIVE-QA-GUIDE.md](../GO-LIVE-QA-GUIDE.md)** - Complete pre-cohort QA gate for content, workflows, Classroom, podcasts, and human testing --- diff --git a/admin/qa-bundle/.github/ISSUE_TEMPLATE/workshop-registration.yml b/admin/qa-bundle/.github/ISSUE_TEMPLATE/workshop-registration.yml new file mode 100644 index 0000000..c759d1e --- /dev/null +++ b/admin/qa-bundle/.github/ISSUE_TEMPLATE/workshop-registration.yml @@ -0,0 +1,90 @@ +name: "Workshop Registration - GIT Going with GitHub" +description: "Register for the GIT Going with GitHub workshop ([WORKSHOP_DATE_DAY1] and [WORKSHOP_DATE_DAY2])" +title: "[REGISTER] GIT Going with GitHub - [WORKSHOP_DATE]" +labels: ["registration"] +assignees: [] +body: + - type: markdown + attributes: + value: | + ## Welcome! You are registering for GIT Going with GitHub. + + **Dates:** [WORKSHOP_DATE_DAY1] and [WORKSHOP_DATE_DAY2] + **Time:** [WORKSHOP_TIME] (both days) + **Cost:** Free + **Capacity:** 75 participants + + Filling out this form is your first GitHub interaction - and it counts. You are already learning. All fields below are accessible with NVDA, JAWS, and VoiceOver. + + - type: input + id: first-name + attributes: + label: First Name + description: Your first name as you would like to be addressed during the workshop. + placeholder: Jane + validations: + required: true + + - type: input + id: last-name + attributes: + label: Last Name + description: Your last name. + placeholder: Doe + validations: + required: true + + - type: input + id: email + attributes: + label: Email Address + description: We will use this to send you Zoom links and workshop materials before the event. + placeholder: jane.doe@example.com + validations: + required: true + + - type: dropdown + id: proficiency + attributes: + label: GitHub Proficiency Level + description: How would you describe your current experience with GitHub? There is no wrong answer - this helps us prepare the right level of support for you. + options: + - "Brand new - I have never used GitHub before" + - "Beginner - I have a GitHub account but have not done much with it" + - "Intermediate - I have created repositories, filed issues, or opened pull requests" + - "Experienced - I use GitHub regularly for projects or work" + validations: + required: true + + - type: dropdown + id: screen-reader + attributes: + label: Primary Screen Reader + description: Which screen reader do you primarily use? This helps us prepare targeted guidance. + options: + - "NVDA (Windows)" + - "JAWS (Windows)" + - "VoiceOver (macOS)" + - "VoiceOver (iOS)" + - "Other or none" + validations: + required: false + + - type: textarea + id: questions + attributes: + label: Questions or Accommodations + description: Any questions about the workshop, or accommodations we should arrange? Leave blank if none. + placeholder: | + Can I attend only Day 1? + I use a refreshable braille display - will that work? + validations: + required: false + + - type: markdown + attributes: + value: | + --- + **What happens next:** After you submit, you will see a confirmation comment on your issue. We will email your Zoom link before the workshop. If you have questions, [file an issue](https://github.com/community-access/git-going-with-github/issues) in the workshop repository. + + Welcome aboard. You belong here. diff --git a/admin/qa-bundle/.github/workflows/registration.yml b/admin/qa-bundle/.github/workflows/registration.yml new file mode 100644 index 0000000..01d3b0b --- /dev/null +++ b/admin/qa-bundle/.github/workflows/registration.yml @@ -0,0 +1,480 @@ +name: Registration - Welcome & CSV Export + +on: + issues: + types: [opened] + workflow_dispatch: + +permissions: + contents: write + issues: write + +jobs: + welcome: + name: Welcome New Registrant + runs-on: ubuntu-latest + if: >- + github.event_name == 'issues' && + github.event.action == 'opened' && + contains(github.event.issue.title, '[REGISTER]') + steps: + - name: Check for duplicate registration + id: dup-check + uses: actions/github-script@v7 + with: + script: | + const username = context.payload.issue.user.login; + const currentIssueNumber = context.issue.number; + + // Find existing registration issues by this user + const existingIssues = await github.paginate(github.rest.issues.listForRepo, { + owner: context.repo.owner, + repo: context.repo.repo, + labels: 'registration', + state: 'all', + per_page: 100 + }); + + const priorRegistration = existingIssues.find( + issue => issue.user.login === username && issue.number !== currentIssueNumber + ); + + if (priorRegistration) { + core.setOutput('is_duplicate', 'true'); + core.setOutput('original_issue', priorRegistration.number); + } else { + core.setOutput('is_duplicate', 'false'); + } + + - name: Handle duplicate registration + if: steps.dup-check.outputs.is_duplicate == 'true' + uses: actions/github-script@v7 + env: + ORIGINAL_ISSUE: ${{ steps.dup-check.outputs.original_issue }} + with: + script: | + const originalIssue = parseInt(process.env.ORIGINAL_ISSUE, 10); + + await github.rest.issues.createComment({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: context.issue.number, + body: `## You are already registered! + + Hi @${context.payload.issue.user.login}, it looks like you already registered in issue #${originalIssue}. No need to register again — your spot is saved! + + We have closed this issue since your original registration is already on file. If you need to update your details, please comment on your original issue #${originalIssue}. + + Questions? [File an issue](https://github.com/community-access/git-going-with-github/issues) in the workshop repository.` + }); + + await github.rest.issues.addLabels({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: context.issue.number, + labels: ['duplicate'] + }); + + await github.rest.issues.update({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: context.issue.number, + state: 'closed', + state_reason: 'not_planned' + }); + + - name: Check capacity + id: capacity-check + if: steps.dup-check.outputs.is_duplicate == 'false' + uses: actions/github-script@v7 + with: + script: | + const MAX_CAPACITY = 75; + + // Count unique registered users (excluding this issue) + const existingIssues = await github.paginate(github.rest.issues.listForRepo, { + owner: context.repo.owner, + repo: context.repo.repo, + labels: 'registration', + state: 'all', + per_page: 100 + }); + + const currentIssueNumber = context.issue.number; + const uniqueUsers = new Set(); + for (const issue of existingIssues) { + if (issue.number !== currentIssueNumber) { + uniqueUsers.add(issue.user.login); + } + } + + const currentCount = uniqueUsers.size; + core.setOutput('count', currentCount); + + if (currentCount >= MAX_CAPACITY) { + core.setOutput('is_full', 'true'); + } else { + core.setOutput('is_full', 'false'); + } + + - name: Handle registration full + if: steps.dup-check.outputs.is_duplicate == 'false' && steps.capacity-check.outputs.is_full == 'true' + uses: actions/github-script@v7 + with: + script: | + await github.rest.issues.createComment({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: context.issue.number, + body: `## Registration is currently full + + Hi @${context.payload.issue.user.login}, thank you for your interest in GIT Going with GitHub! Unfortunately, all 75 spots have been filled. + + We have added you to the waitlist. If a spot opens up, we will let you know right here on this issue. + + Questions? [File an issue](https://github.com/community-access/git-going-with-github/issues) in the workshop repository.` + }); + + await github.rest.issues.addLabels({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: context.issue.number, + labels: ['waitlist'] + }); + + - name: Invite registrant to classroom organization (optional) + id: classroom-invite + if: >- + steps.dup-check.outputs.is_duplicate == 'false' && + steps.capacity-check.outputs.is_full == 'false' && + vars.CLASSROOM_ORG != '' + uses: actions/github-script@v7 + env: + CLASSROOM_ORG: ${{ vars.CLASSROOM_ORG }} + with: + github-token: ${{ secrets.CLASSROOM_ORG_ADMIN_TOKEN }} + script: | + const org = process.env.CLASSROOM_ORG; + const username = context.payload.issue.user.login; + const userId = context.payload.issue.user.id; + let status = 'skipped'; + + try { + await github.rest.orgs.checkMembershipForUser({ org, username }); + status = 'already-member'; + core.info(`${username} is already a member of ${org}`); + } catch (error) { + if (error.status !== 404) { + throw error; + } + + const invites = await github.paginate(github.rest.orgs.listPendingInvitations, { + org, + per_page: 100 + }); + + const hasPendingInvite = invites.some(invite => + (invite.login || '').toLowerCase() === username.toLowerCase() + ); + + if (hasPendingInvite) { + status = 'already-invited'; + core.info(`${username} already has a pending invite to ${org}`); + } else { + await github.rest.orgs.createInvitation({ + org, + invitee_id: userId, + role: 'direct_member' + }); + status = 'invited'; + core.info(`Sent org invite for ${username} to ${org}`); + } + } + + core.setOutput('status', status); + + - name: Post welcome comment + if: steps.dup-check.outputs.is_duplicate == 'false' && steps.capacity-check.outputs.is_full == 'false' + uses: actions/github-script@v7 + env: + CLASSROOM_ORG: ${{ vars.CLASSROOM_ORG }} + DAY1_ASSIGNMENT_URL: ${{ vars.CLASSROOM_DAY1_ASSIGNMENT_URL }} + DAY2_ASSIGNMENT_URL: ${{ vars.CLASSROOM_DAY2_ASSIGNMENT_URL }} + CLASSROOM_INVITE_STATUS: ${{ steps.classroom-invite.outputs.status }} + with: + script: | + const org = process.env.CLASSROOM_ORG; + const day1 = (process.env.DAY1_ASSIGNMENT_URL || '').trim(); + const day2 = (process.env.DAY2_ASSIGNMENT_URL || '').trim(); + const inviteStatus = (process.env.CLASSROOM_INVITE_STATUS || '').trim(); + + let classroomSection = ''; + if (day1 || day2 || inviteStatus) { + const lines = ['## Classroom Access']; + + if (inviteStatus === 'invited') { + lines.push(`- We sent an organization invitation for \`${org}\`. Please accept it from your GitHub notifications or email.`); + } else if (inviteStatus === 'already-invited') { + lines.push(`- You already have a pending invitation for \`${org}\`. Please accept it before using assignment links.`); + } else if (inviteStatus === 'already-member') { + lines.push(`- You are already a member of \`${org}\`.`); + } + + if (day1) { + lines.push(`- Day 1 assignment link: ${day1}`); + } + if (day2) { + lines.push(`- Day 2 assignment link: ${day2}`); + } + + if (lines.length > 1) { + classroomSection = `\n\n${lines.join('\n')}`; + } + } + + await github.rest.issues.createComment({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: context.issue.number, + body: `## Welcome to GIT Going with GitHub! + + Hi @${context.payload.issue.user.login}, thank you for registering! We are excited to have you join us. + + Your registration is confirmed. Please register for the Zoom session here: [Register on Zoom](https://us06web.zoom.us/meeting/register/YdAAvwzAQUCYpPpNtAlG3g) + + In the meantime, you can get a head start with the [Pre-Workshop Setup Guide](https://community-access.github.io/git-going-with-github/docs/00-pre-workshop-setup.html). + + ${classroomSection} + + If you have any questions, [file an issue](https://github.com/community-access/git-going-with-github/issues) in the workshop repository. + + See you at the workshop!` + }); + + - name: Add registration label + if: steps.dup-check.outputs.is_duplicate == 'false' && steps.capacity-check.outputs.is_full == 'false' + uses: actions/github-script@v7 + with: + script: | + try { + await github.rest.issues.addLabels({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: context.issue.number, + labels: ['registration'] + }); + } catch (e) { + console.log('Label may already exist:', e.message); + } + + export-csv: + name: Export Registrations to CSV + runs-on: ubuntu-latest + if: >- + (github.event_name == 'workflow_dispatch') || + (github.event_name == 'issues' && + github.event.action == 'opened' && + contains(github.event.issue.title, '[REGISTER]')) + steps: + - name: Generate CSV from registration issues + uses: actions/github-script@v7 + with: + script: | + const fs = require('fs'); + + // Fetch all issues with the registration label + const issues = await github.paginate(github.rest.issues.listForRepo, { + owner: context.repo.owner, + repo: context.repo.repo, + labels: 'registration', + state: 'all', + per_page: 100 + }); + + // Parse issue body fields (GitHub YAML forms use ### heading + content pattern) + function parseField(body, fieldName) { + if (!body) return ''; + // Match the pattern: ### Field Name\n\nValue + // Also handle ### Field Name\r\n\r\nValue + const regex = new RegExp(`### ${fieldName}\\s*\\n+([\\s\\S]*?)(?=\\n### |$)`, 'i'); + const match = body.match(regex); + if (!match) return ''; + let value = match[1].trim(); + // Remove _No response_ placeholder + if (value === '_No response_') return ''; + // Escape CSV: quote fields containing commas, quotes, or newlines + if (value.includes(',') || value.includes('"') || value.includes('\n')) { + value = '"' + value.replace(/"/g, '""') + '"'; + } + return value; + } + + // Fetch org members and pending invitations for OrgStatus column + let orgMembers = new Set(); + let pendingInvites = new Set(); + try { + const members = await github.paginate(github.rest.orgs.listMembers, { + org: context.repo.owner, + per_page: 100 + }); + for (const m of members) orgMembers.add(m.login.toLowerCase()); + + const invites = await github.paginate(github.rest.orgs.listPendingInvitations, { + org: context.repo.owner, + per_page: 100 + }); + for (const inv of invites) { + if (inv.login) pendingInvites.add(inv.login.toLowerCase()); + } + } catch (e) { + console.log('Could not fetch org membership (may lack admin scope):', e.message); + } + + // Build CSV + const headers = [ + 'IssueNumber', + 'State', + 'CreatedAt', + 'GitHubUsername', + 'FirstName', + 'LastName', + 'Email', + 'ProficiencyLevel', + 'PrimaryScreenReader', + 'QuestionsOrAccommodations', + 'OrgStatus' + ]; + + let csv = headers.join(',') + '\n'; + + // Deduplicate by GitHub username, keeping only the earliest registration + const seen = new Set(); + const sortedIssues = issues.sort((a, b) => new Date(a.created_at) - new Date(b.created_at)); + + for (const issue of sortedIssues) { + const username = issue.user.login; + if (seen.has(username)) continue; + seen.add(username); + + // Determine org membership status + const uLower = username.toLowerCase(); + let orgStatus = 'needs-invite'; + if (orgMembers.has(uLower)) orgStatus = 'member'; + else if (pendingInvites.has(uLower)) orgStatus = 'pending'; + + const row = [ + issue.number, + issue.state.toUpperCase(), + issue.created_at.split('T')[0], + username, + parseField(issue.body, 'First Name'), + parseField(issue.body, 'Last Name'), + parseField(issue.body, 'Email Address'), + parseField(issue.body, 'GitHub Proficiency Level'), + parseField(issue.body, 'Primary Screen Reader'), + parseField(issue.body, 'Questions or Accommodations'), + orgStatus + ]; + csv += row.join(',') + '\n'; + } + + // Write CSV file + fs.mkdirSync('.github/data', { recursive: true }); + fs.writeFileSync('.github/data/registration-data.csv', csv, 'utf-8'); + console.log(`Exported ${seen.size} unique registration(s) from ${issues.length} total issue(s) to .github/data/registration-data.csv`); + + - name: Upload CSV as artifact + uses: actions/upload-artifact@v4 + with: + name: registration-data + path: .github/data/registration-data.csv + retention-days: 90 + + sync-roster: + name: Sync Student Roster (No PII) + runs-on: ubuntu-latest + if: >- + (github.event_name == 'workflow_dispatch') || + (github.event_name == 'issues' && + github.event.action == 'opened' && + contains(github.event.issue.title, '[REGISTER]')) + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Build roster from registration issues + uses: actions/github-script@v7 + with: + script: | + const fs = require('fs'); + + // Fetch all issues with the registration label + const issues = await github.paginate(github.rest.issues.listForRepo, { + owner: context.repo.owner, + repo: context.repo.repo, + labels: 'registration', + state: 'all', + per_page: 100 + }); + + function parseField(body, fieldName) { + if (!body) return ''; + const regex = new RegExp(`### ${fieldName}\\s*\\n+([\\s\\S]*?)(?=\\n### |$)`, 'i'); + const match = body.match(regex); + if (!match) return ''; + const value = match[1].trim(); + if (value === '_No response_') return ''; + return value; + } + + // Load existing roster to preserve runtime state (mergedPRs, currentLevel, badges) + const rosterPath = '.github/data/student-roster.json'; + let roster = { students: [] }; + if (fs.existsSync(rosterPath)) { + roster = JSON.parse(fs.readFileSync(rosterPath, 'utf8')); + } + const existing = new Map(roster.students.map(s => [s.username, s])); + + // Deduplicate by username, keeping earliest registration + const seen = new Set(); + const sorted = issues.sort((a, b) => new Date(a.created_at) - new Date(b.created_at)); + const students = []; + + for (const issue of sorted) { + const username = issue.user.login; + if (seen.has(username)) continue; + seen.add(username); + + // Preserve existing runtime fields if student was already in roster + const prev = existing.get(username) || {}; + + // Only store non-PII operational fields + students.push({ + username, + joinedDate: prev.joinedDate || issue.created_at.split('T')[0], + mergedPRs: prev.mergedPRs || 0, + currentLevel: prev.currentLevel || 'Beginner', + interests: prev.interests || ['accessibility', 'open-source'], + timezone: prev.timezone || 'Unknown' + }); + } + + // Update roster — preserve cohort metadata, replace students list + roster.students = students; + roster._schema_note = 'Auto-populated by registration workflow. Contains only GitHub usernames and workflow state. No personal information.'; + + fs.mkdirSync('.github/data', { recursive: true }); + fs.writeFileSync(rosterPath, JSON.stringify(roster, null, 2) + '\n', 'utf-8'); + console.log(`Roster synced: ${students.length} student(s) from ${issues.length} registration issue(s)`); + + - name: Commit roster update + run: | + git config user.name "github-actions[bot]" + git config user.email "41898282+github-actions[bot]@users.noreply.github.com" + git add .github/data/student-roster.json + if git diff --cached --quiet; then + echo "No roster changes to commit" + else + git commit -m "chore: sync student roster from registrations [skip ci]" + git push + fi diff --git a/admin/qa-bundle/GO-LIVE-QA-GUIDE.md b/admin/qa-bundle/GO-LIVE-QA-GUIDE.md new file mode 100644 index 0000000..5249277 --- /dev/null +++ b/admin/qa-bundle/GO-LIVE-QA-GUIDE.md @@ -0,0 +1,378 @@ +# 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, podcast materials, accessibility, and human test coverage. + +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. + +## 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. +- [ ] Podcast catalog validation passes. +- [ ] RSS feed validation passes for the current audio state. +- [ ] 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 issue form template and labels are configured (`workshop-registration.yml`, `registration`, `duplicate`, `waitlist`). +- [ ] 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. +- [ ] Smoke repo confirms all required workflow files are present (PR validation, content validation, progression, skills progression, and all autograders). +- [ ] 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. +- [ ] Challenge 1 can be seeded and completed. +- [ ] Challenge 10 can be seeded and completed. +- [ ] Aria posts PR feedback on a test pull request. +- [ ] Student Progression Bot creates the next challenge when a challenge issue is closed. +- [ ] Autograding runs and reports results in GitHub Classroom. +- [ ] 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. +- [ ] All in-scope automation workflows and facilitator scripts were validated with expected behavior and evidence. +- [ ] All blocking findings have a fix, owner, or written release exception. + +## Source Of Truth + +The following table lists each release artifact and the document that controls it. + +| Area | Source document | +|---|---| +| Classroom deployment | [classroom/README.md](classroom/README.md) | +| Classroom copy-paste setup pack | [admin/classroom/README.md](admin/classroom/README.md) | +| End-to-end operator runbook (registration to completion, podcast excluded) | [admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md](admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md) | +| Human challenge walkthrough | [classroom/HUMAN_TEST_MATRIX.md](classroom/HUMAN_TEST_MATRIX.md) | +| Facilitator operations | [admin/FACILITATOR_OPERATIONS.md](admin/FACILITATOR_OPERATIONS.md) | +| Facilitator guide | [admin/FACILITATOR_GUIDE.md](admin/FACILITATOR_GUIDE.md) | +| Student challenge hub | [docs/CHALLENGES.md](docs/CHALLENGES.md) | +| Podcast pipeline | [podcasts/README.md](podcasts/README.md) | +| Podcast regeneration runbook | [podcasts/REGENERATION.md](podcasts/REGENERATION.md) | +| Post-workshop cleanup | [classroom/teardown-checklist.md](classroom/teardown-checklist.md) | + +## Roles + +- **Release owner:** owns the final go or no-go decision. +- **Classroom tester:** creates assignments, accepts invites with a test student account, and validates repository creation. +- **Automation tester:** checks workflows, seeding scripts, Aria feedback, progression, and autograding. +- **Accessibility tester:** tests with NVDA, JAWS, VoiceOver, keyboard-only navigation, zoom, and high contrast where available. +- **Curriculum tester:** reads chapters, appendices, challenge templates, solutions, and facilitator instructions for accuracy and consistency. +- **Podcast tester:** validates podcast scripts, transcripts, RSS metadata, and audio availability if audio has been generated. + +One person may hold multiple roles, but the release owner should not be the only human tester. + +## Phase 1: Local Repository Health + +Run these commands from the repository root. + +```powershell +npm run test:automation +npm run validate:podcasts +npm run validate:podcast-feed +npm run build:html +git diff --check +``` + +Expected results: + +- `npm run test:automation` reports all tests passing. +- `npm run validate:podcasts` reports 54 catalog episodes and passes. +- `npm run validate:podcast-feed` passes. If audio files have not been generated yet, the transcript-only warning is acceptable. +- `npm run build:html` completes without errors. +- `git diff --check` has no trailing-whitespace or conflict-marker errors. On Windows, LF-to-CRLF warnings may appear and are not release blockers by themselves. + +Record the command output summary in the release notes or QA issue. + +## Phase 2: Content Inventory Review + +Every content file must be reviewed before go-live. Use this checklist to assign coverage. + +- [ ] Root docs: [README.md](README.md), [BUILD.md](BUILD.md), [REGISTER.md](REGISTER.md), [CONTRIBUTING.md](CONTRIBUTING.md), [SECURITY.md](SECURITY.md), [REPOSITORY_SECURITY.md](REPOSITORY_SECURITY.md). +- [ ] Student onboarding: [docs/get-going.md](docs/get-going.md), [docs/course-guide.md](docs/course-guide.md), and [docs/student-onboarding.md](docs/student-onboarding.md). +- [ ] Core chapters: [docs/00-pre-workshop-setup.md](docs/00-pre-workshop-setup.md) through [docs/21-next-steps.md](docs/21-next-steps.md). +- [ ] Appendices: [docs/appendix-a-glossary.md](docs/appendix-a-glossary.md) through [docs/appendix-z-github-skills.md](docs/appendix-z-github-skills.md). +- [ ] Challenge hub: [docs/CHALLENGES.md](docs/CHALLENGES.md). +- [ ] Challenge solutions: all files in [docs/solutions](docs/solutions/README.md). +- [ ] Learning Room template docs: all Markdown files under [learning-room](learning-room/README.md). +- [ ] Issue templates: all files under `learning-room/.github/ISSUE_TEMPLATE/`. +- [ ] Student automation guides: all Markdown files under `learning-room/.github/`. +- [ ] Facilitator guides: all Markdown files under [admin](admin/README.md) and [admin/classroom](admin/classroom/README.md). +- [ ] Classroom setup artifacts: all Markdown, JSON, CSV, and YAML files under [classroom](classroom/README.md). +- [ ] Podcast docs, scripts, manifests, transcripts, and generated site metadata under [podcasts](podcasts/README.md). +- [ ] Generated HTML under `html/` after `npm run build:html`. + +For each file, verify: + +- [ ] The title matches the current GitHub Classroom model. +- [ ] The file does not tell students they are working in a single shared repository unless it is explicitly discussing legacy history. +- [ ] Branch names use the current conventions: `learn/` for the Day 1 practice branch, or short-lived `fix/...` branches for focused PR exercises. +- [ ] Challenge numbers, titles, and evidence requirements match [docs/CHALLENGES.md](docs/CHALLENGES.md). +- [ ] Links resolve or are intentionally broken practice targets in the Learning Room template. +- [ ] Instructions are concise enough for a facilitator to read aloud. +- [ ] Screen reader steps avoid visual-only wording when a keyboard or structural path is available. +- [ ] Tables have a preceding sentence explaining what they contain. +- [ ] Diagrams, images, and SVGs have nearby text alternatives in the surrounding documentation. + +## Phase 3: Classroom Deployment Dry Run + +Use a real GitHub Classroom with disposable test accounts. Do not use a facilitator account as the student account. + +### Organization And Template Readiness + +- [ ] Confirm the classroom organization exists and facilitators have owner or admin access. +- [ ] Confirm `Community-Access/learning-room-template` exists and is the template repository selected for both assignments. +- [ ] Confirm GitHub Actions is enabled for the template repository. +- [ ] Confirm `GITHUB_TOKEN` has read and write permissions in the template repository settings. +- [ ] Confirm Actions can create and approve pull requests if Classroom feedback PRs are used. +- [ ] Confirm the Learning Room template includes `.github/workflows/pr-validation-bot.yml`. +- [ ] Confirm the Learning Room template includes `.github/workflows/student-progression.yml`. +- [ ] Confirm the Learning Room template includes all autograder workflows. +- [ ] Confirm the Learning Room template includes all challenge issue templates and bonus templates. + +### Day 1 Assignment + +- [ ] Create the Day 1 assignment using [classroom/assignment-day1-you-belong-here.md](classroom/assignment-day1-you-belong-here.md). +- [ ] Use private individual repositories. +- [ ] Enable feedback pull requests. +- [ ] Add every Day 1 autograding test from [classroom/autograding-day1.json](classroom/autograding-day1.json). +- [ ] Save the Day 1 invite link. +- [ ] Accept the invite with a test student account. +- [ ] Confirm the student repository appears in the Classroom dashboard. +- [ ] Confirm the repository name follows the expected pattern. +- [ ] Confirm the template files copied correctly. +- [ ] Seed Challenge 1: + +```powershell +scripts/classroom/Seed-LearningRoomChallenge.ps1 -Repository Community-Access-Classroom/learning-room-test-student -Challenge 1 -Assignee test-student +``` + +- [ ] Confirm Challenge 1 appears in the student repository. + +### Day 2 Assignment + +- [ ] Create the Day 2 assignment using [classroom/assignment-day2-you-can-build-this.md](classroom/assignment-day2-you-can-build-this.md). +- [ ] Use private individual repositories. +- [ ] Enable feedback pull requests. +- [ ] Add every Day 2 autograding test from [classroom/autograding-day2.json](classroom/autograding-day2.json). +- [ ] Save the Day 2 invite link. +- [ ] Accept the invite with the test student account. +- [ ] Confirm the Day 2 repository appears in the Classroom dashboard. +- [ ] Seed Challenge 10: + +```powershell +scripts/classroom/Seed-LearningRoomChallenge.ps1 -Repository Community-Access-Classroom/learning-room-test-student-day2 -Challenge 10 -Assignee test-student +``` + +- [ ] Confirm Challenge 10 appears in the student repository. + +## Phase 4: Workflow And Automation QA + +Run these checks in disposable student repositories created by GitHub Classroom. + +### Aria PR Validation Bot + +- [ ] Open a PR with a clear title, body, and `Closes #N` reference. +- [ ] Confirm the first-time contributor welcome comment appears on the first PR. +- [ ] Confirm the PR Validation Report appears or updates within 60 seconds. +- [ ] Push another commit and confirm the existing validation comment updates instead of duplicating. +- [ ] Add an intentional issue, such as vague link text, and confirm the bot explains the problem. +- [ ] Fix the issue and confirm the validation result improves. +- [ ] Comment `@aria-bot help` and confirm the help responder answers. +- [ ] Comment with `merge conflict` and confirm the conflict guidance appears. +- [ ] Confirm bot-authored comments do not trigger an infinite response loop. + +### Student Progression Bot + +- [ ] Close Challenge 1 and confirm Challenge 2 appears. +- [ ] Continue closing challenges until Challenge 9 appears. +- [ ] Seed Challenge 10 and confirm the Day 2 sequence starts correctly. +- [ ] Close Challenge 10 and confirm Challenge 11 appears. +- [ ] Confirm duplicate challenge issues are not created if the workflow reruns. +- [ ] Confirm the assigned user is correct on each generated challenge. +- [ ] Confirm each generated challenge links to the right chapter and solution reference. + +### Autograders + +- [ ] Challenge 4 branch test passes when a non-default branch exists. +- [ ] Challenge 5 commit test passes when the student commits a real file change. +- [ ] Challenge 6 PR test passes when the PR references the correct issue. +- [ ] Challenge 7 conflict test fails while conflict markers remain. +- [ ] Challenge 7 conflict test passes after conflict markers are removed. +- [ ] Challenge 9 merge/readiness checks report useful results. +- [ ] Challenge 10 local commit test passes after clone, branch, commit, and push. +- [ ] Challenge 14 template test validates a structured issue template. +- [ ] Challenge 16 capstone test validates the required agent contribution evidence. + +### Seeding Scripts + +- [ ] `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. +- [ ] Script failures show a clear error message and do not partially hide the problem. + +## Phase 5: Human Challenge Walkthrough + +Use [classroom/HUMAN_TEST_MATRIX.md](classroom/HUMAN_TEST_MATRIX.md) as the detailed scenario list. This section is the go-live summary gate. + +### Day 1 Core Path + +- [ ] Challenge 1: Find Your Way Around. +- [ ] Challenge 2: File Your First Issue. +- [ ] Challenge 3: Join the Conversation. +- [ ] Challenge 4: Branch Out. +- [ ] Challenge 5: Make Your Mark. +- [ ] Challenge 6: Open Your First Pull Request. +- [ ] Challenge 7: Survive a Merge Conflict. +- [ ] Challenge 8: The Culture Layer. +- [ ] Challenge 9: Merge Day. + +### Day 2 Core Path + +- [ ] Challenge 10: Go Local. +- [ ] Challenge 11: Open a Day 2 PR. +- [ ] Challenge 12: Review Like a Pro. +- [ ] Challenge 13: AI as Your Copilot. +- [ ] Challenge 14: Template Remix. +- [ ] Challenge 15: Meet the Agents. +- [ ] Challenge 16: Build Your Agent. + +### Bonus Path + +- [ ] Bonus A: Improve an Agent. +- [ ] Bonus B: Document Your Journey. +- [ ] Bonus C: Group Challenge. +- [ ] Bonus D: Notifications. +- [ ] Bonus E: Git History. + +For each challenge, record: + +- [ ] The issue appeared at the expected time. +- [ ] The issue instructions were understandable without facilitator translation. +- [ ] The linked chapter helped complete the task. +- [ ] The evidence prompt was clear. +- [ ] The bot or autograder response was useful. +- [ ] The next challenge unlocked correctly. +- [ ] The reference solution matched the challenge. + +## Phase 6: Accessibility QA + +Run accessibility testing with at least one screen reader and one keyboard-only tester. Use more assistive technology coverage when possible. + +- [ ] NVDA with Firefox or Chrome: complete Challenge 1, Challenge 6, Challenge 7, and one Day 2 challenge. +- [ ] JAWS with Chrome or Edge: complete issue creation, PR creation, review, and merge checks. +- [ ] VoiceOver with Safari or Chrome: accept Classroom invite, navigate repo, edit file, and read PR diff. +- [ ] Keyboard-only: complete invite acceptance, issue creation, PR creation, and review submission without a mouse. +- [ ] Low vision: verify 200 percent zoom, high contrast, browser zoom, and focus visibility across GitHub, docs, and generated HTML. +- [ ] Confirm all critical links have descriptive text. +- [ ] Confirm all tables in docs have a preceding explanation. +- [ ] Confirm images and diagrams have meaningful surrounding text or alt text. +- [ ] Confirm generated HTML task-list checkboxes are not duplicated. +- [ ] Confirm conflict-marker examples render as examples and do not break Git diff checks. + +## Phase 7: Podcast And Audio QA + +The podcast material is part of the release. Test it even if audio has not been regenerated yet. + +- [ ] `npm run validate:podcasts` passes. +- [ ] `npm run validate:podcast-feed` passes. +- [ ] Podcast catalog lists 54 companion episodes. +- [ ] Challenge Coach bundles exist for all 16 core challenges and 5 bonus challenges. +- [ ] Each chapter and appendix points to the intended podcast entry. +- [ ] Transcript scripts avoid stale shared-repository boilerplate. +- [ ] Speaker markers are consistent in generated scripts. +- [ ] RSS feed state is documented: transcript-only or audio-ready. +- [ ] If audio exists, every MP3 enclosure URL resolves. +- [ ] If audio exists, a human tester listens to a sample from Day 1, Day 2, appendices, and Challenge Coach. +- [ ] Podcast instructions do not contradict the current private Learning Room model. + +## Phase 8: Facilitator Dry Run + +Run this as a timed rehearsal before student testing. + +- [ ] Facilitator can find this guide from [README.md](README.md), [admin/README.md](admin/README.md), and [classroom/README.md](classroom/README.md). +- [ ] Facilitator can explain the architecture in under 2 minutes. +- [ ] Facilitator can create Assignment 1 without guessing any setting. +- [ ] Facilitator can create Assignment 2 without guessing any setting. +- [ ] Facilitator can seed Challenge 1 and Challenge 10 from PowerShell. +- [ ] Facilitator can seed peer simulation artifacts. +- [ ] Facilitator can start a merge conflict challenge. +- [ ] Facilitator can read Aria feedback and decide whether it is correct. +- [ ] Facilitator can override or manually support a student if automation fails. +- [ ] Facilitator can explain how Day-2-only participants enter the course. +- [ ] Facilitator can explain what to do when a student joins late. +- [ ] Facilitator can run post-workshop teardown. + +## Issue Severity + +The following table defines release-blocking severity levels. + +| Severity | Meaning | Release action | +|---|---|---| +| Blocker | Prevents assignment creation, repository creation, challenge progression, PR validation, accessibility use, or student safety | Fix before release | +| High | Causes confusing instructions, broken links in required paths, wrong challenge evidence, or broken generated content | Fix before release unless release owner approves exception | +| Medium | Causes friction but has a clear workaround | Fix before or immediately after release | +| Low | Typo, minor wording, or non-blocking polish | Fix when practical | + +## QA Evidence Log Template + +Copy this template into a release issue or testing document. + +```markdown +## QA Evidence Log + +Release candidate: +Date: +Release owner: +Classroom tester: +Automation tester: +Accessibility tester: +Curriculum tester: +Podcast tester: + +### Automated Checks +- npm run test:automation: +- npm run validate:podcasts: +- npm run validate:podcast-feed: +- npm run build:html: +- git diff --check: + +### Classroom Dry Run +- Day 1 assignment URL: +- Day 2 assignment URL: +- Test student account: +- Day 1 test repository: +- Day 2 test repository: + +### Human Walkthrough +- Day 1 challenges completed: +- Day 2 challenges completed: +- Bonus challenges completed: +- Accessibility coverage: +- Podcast coverage: + +### Findings +| ID | Severity | Area | Finding | Owner | Status | +|---|---|---|---|---|---| + +### Release Decision +- [ ] Go +- [ ] No-go +- Notes: +``` + +## Final Go-Live Checklist + +- [ ] All required automated checks passed. +- [ ] All required Classroom dry-run checks passed. +- [ ] Human testers completed Day 1, Day 2, bonus, accessibility, and podcast coverage. +- [ ] No open Blocker findings remain. +- [ ] No open High findings remain without written release-owner exception. +- [ ] Invite links are stored in the facilitator runbook and student communications. +- [ ] Facilitators know how to seed Challenge 1 and Challenge 10. +- [ ] Facilitators know how to recover when Aria, progression, or autograding fails. +- [ ] Student-facing instructions match the current GitHub Classroom private-repository model. +- [ ] Generated HTML and podcast site have been rebuilt from the final sources. +- [ ] Release owner has recorded the final decision. \ No newline at end of file diff --git a/admin/qa-bundle/README.md b/admin/qa-bundle/README.md new file mode 100644 index 0000000..c93f67f --- /dev/null +++ b/admin/qa-bundle/README.md @@ -0,0 +1,38 @@ +# QA Bundle (Grab-and-Go) + +This folder is a convenience copy of the files needed to run end-to-end QA for the course (excluding podcast workflows). + +## What this bundle is for + +Use this folder when you want quick local access to all key QA artifacts without navigating the full repo. + +## Start here + +1. [admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md](admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md) +2. [GO-LIVE-QA-GUIDE.md](GO-LIVE-QA-GUIDE.md) +3. [admin/qa-readiness/UNIT-TEST-RESULTS-2026-05-08.md](admin/qa-readiness/UNIT-TEST-RESULTS-2026-05-08.md) + +## Included content sets + +- Registration deployment and QA docs and workflow files. +- Classroom deployment and autograding setup docs. +- Learning Room automation docs, workflows, and issue templates. +- Facilitator scripts for template sync, seeding, conflict setup, and recovery. +- Challenge definitions and student onboarding references. +- Local unit-test readiness evidence. + +## HTML copy of E2E runbook + +- [admin/LEARNING-ROOM-E2E-QA-RUNBOOK.html](admin/LEARNING-ROOM-E2E-QA-RUNBOOK.html) + +## Important notes + +- This bundle is a convenience snapshot, not the canonical source of truth. +- Canonical files remain in the repository root paths. +- Rebuild this bundle after significant workflow/challenge/runbook updates. + +## Local vs GitHub deployment for unit tests + +- Unit tests run locally with `npm run test:automation`. +- GitHub deployment is not required to execute local unit tests. +- Hosted GitHub/Classroom gates are still required for final release readiness. diff --git a/admin/qa-bundle/REGISTER.md b/admin/qa-bundle/REGISTER.md new file mode 100644 index 0000000..3cfcb15 --- /dev/null +++ b/admin/qa-bundle/REGISTER.md @@ -0,0 +1,39 @@ +# Student Opt-In + +[Back to Home](https://community-access.org/git-going-with-github/) | [Discussion Forum](https://github.com/community-access/git-going-with-github/discussions) | [Pre-Workshop Setup Guide](https://community-access.org/git-going-with-github/docs/00-pre-workshop-setup.html) + +## Join the next GIT Going with GitHub cohort + +This page provides a fast, self-serve opt-in workflow for students. + +| | | +|---|---| +| **Status** | Open for student opt-in | +| **Current confirmed registrations** | **Loading...** | +| **Cost** | Free | +| **Form** | GitHub issue form with automated confirmation and waitlist handling | + +## Quick opt-in workflow + +1. Sign in to your [GitHub account](https://github.com/login). +2. Open the registration issue form. +3. Submit the form. + +> [**Start Student Opt-In Form**](https://github.com/community-access/git-going-with-github/issues/new?template=workshop-registration.yml&title=%5BREGISTER%5D+GIT+Going+with+GitHub) + +## What happens automatically + +- Duplicate submissions are handled automatically. +- If capacity is available, your registration is confirmed. +- If capacity is full, your issue is placed on the waitlist automatically. + +## Important note + +Registration issues are public because this repository is public. + +## Need help? + +- [File an issue](https://github.com/community-access/git-going-with-github/issues) +- [Join the Discussion Forum](https://github.com/community-access/git-going-with-github/discussions) + +*A [Community Access](https://community-access.org) initiative.* diff --git a/admin/qa-bundle/admin/LEARNING-ROOM-E2E-QA-RUNBOOK.html b/admin/qa-bundle/admin/LEARNING-ROOM-E2E-QA-RUNBOOK.html new file mode 100644 index 0000000..196ceca --- /dev/null +++ b/admin/qa-bundle/admin/LEARNING-ROOM-E2E-QA-RUNBOOK.html @@ -0,0 +1,1890 @@ + + + + + + Learning Room E2E QA Runbook + + + +

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:

+
    +
  1. Registration intake and validation.
    2. +
  2. GitHub Classroom deployment and assignment setup.
    3. +
  3. Test account acceptance and repository seeding.
    4. +
  4. Full student walkthrough of every challenge path.
    5. +
  5. Release sign-off evidence for go-live.
    6. +
+

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

+

The following table lists the source files this runbook consolidates.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
AreaSource file
Registration entry pageREGISTER.md
Registration automation adminREGISTRATION-ADMIN.md
Registration automation quickstartREGISTRATION-QUICKSTART.md
Registration workflow logic.github/workflows/registration.yml
Classroom deploymentclassroom/README.md
Assignment copy and autograding setupadmin/classroom/README.md
Human challenge walkthroughclassroom/HUMAN_TEST_MATRIX.md
Challenge definitionsdocs/CHALLENGES.md
Student starting pathdocs/get-going.md
Grading criteriaclassroom/grading-guide.md
Release gate baselineGO-LIVE-QA-GUIDE.md
+

Required Accounts, Access, and Tools

+

Complete this section before Phase 1.

+
    +
  • Facilitator admin account with Owner or Admin access to the workshop organization and classroom organization.
    • +
  • Dedicated non-admin test student account for acceptance and full challenge walkthrough.
    • +
  • Access to classroom.github.com.
    • +
  • Access to repository settings for secrets and variables.
    • +
  • Local clone of this repository with PowerShell available.
    • +
  • GitHub CLI (gh) installed and authenticated for optional verification commands.
    • +
+

Critical Precondition Gates (No-Go if any fail)

+

Complete all items below before any cohort launch actions.

+
    +
  • Facilitator account can access both organizations involved in operations:
      +
    • Community-Access
      • +
    • Community-Access-Classroom (or your classroom org)
      • +
    +
    • +
  • Facilitator account has verified email and can create/edit Classroom assignments.
    • +
  • Dedicated non-admin test student account exists and can accept invites.
    • +
  • gh auth status succeeds for facilitator account 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:
      +
    • Secret: CLASSROOM_ORG_ADMIN_TOKEN
      • +
    • Variables: CLASSROOM_ORG, CLASSROOM_DAY1_ASSIGNMENT_URL, CLASSROOM_DAY2_ASSIGNMENT_URL
      • +
    +
    • +
  • Registration entry configuration exists and is valid:
      +
    • Issue form template workshop-registration.yml exists
      • +
    • Required labels exist: registration, duplicate, waitlist
      • +
    +
    • +
  • Facilitator can open classroom.github.com, view target classroom org, and create assignments.
    • +
+

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

+
    +
  1. Sign in as the facilitator account on github.com.
    2. +
  2. Open your profile menu, then Your organizations.
    3. +
  3. Confirm both organizations are visible and accessible:
      +
    • Community-Access
      • +
    • Community-Access-Classroom (or your classroom org)
      • +
    +
    4. +
  4. Open both org pages and confirm you can view repositories and settings areas you are expected to manage.
    5. +
  5. Optional CLI verification from repository root:
    6. +
+
gh auth status -h github.com
+gh repo view Community-Access/git-going-with-github
+gh repo view Community-Access/learning-room-template
+
+

Why this matters:

+
    +
  • All downstream setup fails if the facilitator identity is not correctly scoped.
    • +
+

B. Configure registration automation key and variables

+

Repository target: Community-Access/git-going-with-github

+
    +
  1. Open repository Settings.
    2. +
  2. Open Secrets and variables, then Actions.
    3. +
  3. Open the Secrets tab and create or update secret:
      +
    • CLASSROOM_ORG_ADMIN_TOKEN
      • +
    +
    4. +
  4. Open the Variables tab and create or update variables:
      +
    • CLASSROOM_ORG
      • +
    • CLASSROOM_DAY1_ASSIGNMENT_URL
      • +
    • CLASSROOM_DAY2_ASSIGNMENT_URL
      • +
    +
    5. +
  5. Re-open each entry and confirm values have no leading or trailing spaces.
    6. +
  6. Run one registration test and confirm welcome comment contains assignment links when variables are set.
    7. +
+

Why this matters:

+
    +
  • These values drive invite and assignment-link injection in registration responses.
    • +
+

C. Configure template repository Actions permissions

+

Repository target: Community-Access/learning-room-template

+
    +
  1. Open repository Settings.
    2. +
  2. Open Actions, then General.
    3. +
  3. In Actions permissions, ensure Actions are enabled for the repository.
    4. +
  4. In Workflow permissions, set GITHUB_TOKEN to Read and write permissions.
    5. +
  5. Enable Allow GitHub Actions to create and approve pull requests.
    6. +
  6. Save changes.
    7. +
+

Why this matters:

+
    +
  • Template automation and bot workflows require write-capable workflow token behavior.
    • +
+

D. Confirm the repository is a template and hosted in Community-Access

+
    +
  1. Open Community-Access/learning-room-template.
    2. +
  2. Open Settings, then General.
    3. +
  3. Confirm the repository is marked as a template repository.
    4. +
  4. Confirm default branch is main.
    5. +
+

Why this matters:

+
    +
  • Classroom assignment creation depends on the repository being available as a template.
    • +
+

E. Confirm the latest learning-room content is deployed to Community-Access template

+
    +
  1. From repository root, run:
    2. +
+
scripts/classroom/Prepare-LearningRoomTemplate.ps1 -Owner Community-Access -TemplateRepo learning-room-template
+
+
    +
  1. If the script reports changes, open and merge the generated sync pull request in Community-Access/learning-room-template.
    2. +
  2. If the script reports no changes, capture that output as evidence.
    3. +
  3. Verify merged PR (or no-change output) in QA notes.
    4. +
+

Why this matters:

+
    +
  • This is the control point that proves Community-Access template content is current.
    • +
+

F. Prove freshness from a new template-generated repository

+
    +
  1. Run:
    2. +
+
scripts/classroom/Test-LearningRoomTemplate.ps1 -Owner Community-Access -TemplateRepo learning-room-template -KeepSmokeRepo
+
+
    +
  1. Open the retained smoke repository.
    2. +
  2. Compare at least three files changed in the most recent template sync PR:
      +
    • one workflow file
      • +
    • one issue template file
      • +
    • one docs or script file
      • +
    +
    3. +
  3. Confirm file content in smoke repo matches merged sync PR content.
    4. +
  4. Record comparison links and outcome in QA notes.
    5. +
+

Why this matters:

+
    +
  • This proves newly created student repositories inherit the latest template state, not stale content.
    • +
+

Test Artifacts You Will Produce

+

Collect the following evidence while running QA.

+
    +
  • Screenshots of registration confirmation and waitlist behavior.
    • +
  • Screenshot of Day 1 and Day 2 assignment configuration pages.
    • +
  • Screenshot of Day 1 and Day 2 autograding test lists with correct counts.
    • +
  • Link to Learning Room template sync PR (or explicit no-change output) before cohort launch.
    • +
  • Evidence of template smoke validation from a repo created from Community-Access/learning-room-template.
    • +
  • Links to test student Day 1 and Day 2 repositories.
    • +
  • Screenshot or link proving Challenge 1 and Challenge 10 seeding succeeded.
    • +
  • Links to PRs used to validate Aria and autograders.
    • +
  • Evidence that progression creates the next issue after close.
    • +
  • Completed chapter-by-chapter walkthrough tracker for all required docs files.
    • +
  • Completed challenge tracker for Challenges 1 to 16 and Bonus A to E.
    • +
  • Final sign-off checklist with pass/fail and owner notes.
    • +
+

Artifact Capture Procedure (Required)

+

Use this procedure for every artifact in this section:

+
    +
  1. Capture evidence immediately after the validation action completes.
    2. +
  2. Name the evidence with timestamp, phase, and short description.
    3. +
  3. Store URL-based evidence whenever possible; use screenshots when URL evidence is not available.
    4. +
  4. Add one-line context in QA notes describing what the evidence proves.
    5. +
  5. If evidence cannot be captured, log a defect and do not mark the related gate complete.
    6. +
+

Why this matters:

+
    +
  • Sign-off quality depends on auditable evidence, not memory or verbal confirmation.
    • +
+

Runbook Execution Standard (Applies to Every Phase)

+

Follow this standard across the entire runbook.

+
    +
  1. Read the phase goal and pass criteria before performing actions.
    2. +
  2. Execute steps in order unless the runbook explicitly permits parallel execution.
    3. +
  3. After each major step, capture evidence and log result as Pass, Fail, or Blocked.
    4. +
  4. When a step fails, stop, execute troubleshooting guidance, and document outcome before continuing.
    5. +
  5. Do not mark a phase complete until all pass criteria are satisfied or formally risk-accepted.
    6. +
+

Why this matters:

+
    +
  • Consistent execution prevents partial validation and improves handoff reliability between operators.
    • +
+

QA Validation Contract (What, Where, When, How, Expected Experience)

+

Use this section as the operational standard for every phase.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
What to validateWhere to validateWhen expectedHow to validateExpected experience
Registration issue form opens with prefilled titlePublic registration page and GitHub issue formImmediately after selecting registration linkOpen the registration form link from REGISTER.mdForm opens with [REGISTER] prefilled and correct template fields
Registration labels and form template are presentRepository issues/labels and .github/ISSUE_TEMPLATEBefore first registration testVerify labels and workshop-registration.yml existRegistration workflow can label and process issues without setup errors
Registration confirmation behaviorRegistration issue thread and Actions run for registration.ymlWithin 1-3 minutes of issue submissionSubmit test registration and inspect comment and labelsWelcome comment appears, registration label applied, no manual intervention required
Classroom invite link injection in confirmationSame registration issue welcome commentSame workflow run as registration confirmationConfirm assignment URL variables are configured and inspect comment bodyDay 1 and Day 2 links appear exactly once and are clickable
Duplicate registration handlingDuplicate registration issueWithin 1-3 minutes of duplicate submissionSubmit second registration from same accountIssue auto-closed, duplicate label applied, link to original issue included
Waitlist behaviorRegistration issue and labelsWithin 1-3 minutes when capacity threshold is metValidate in safe staging path or controlled testWaitlist message appears and waitlist label applied
Classroom assignment creationGitHub Classroom UIDuring deployment phase before student testingConfigure Day 1 and Day 2 using source docsAssignment fields match source of truth and are published
Student repo creation after acceptanceClassroom dashboard and student account repositories30-60 seconds after invite acceptanceAccept Day 1 and Day 2 invite URLs with test student accountSeparate private repos are created and visible to facilitator and test student
Challenge seedingTest student repository Issues tabWithin 30-90 seconds after seeding script runRun seeding scripts and refresh IssuesCorrect starting challenge appears and is assigned correctly
PR validation feedback (Aria)Test student pull request comments and ActionsWithin approximately 60 seconds after PR open/updateOpen PR and push another commitSingle bot comment appears and updates rather than duplicating
Content validation feedbackTest student PR checks/comments and ActionsWithin approximately 60 seconds after PR open/updateInclude link/markdown/accessibility issues and inspect outputRequired fixes and suggestions are clear and tied to changed files
Progression behaviorTest student Issues tab and Actions for student progressionAfter each challenge issue closureClose challenge issue sequentiallyNext challenge opens automatically with correct number/title
Skills progression behaviorPR merged event and resulting comment/workflow outputAfter PR mergeMerge test PR and inspect workflow outputAchievement/progress feedback posts without workflow failure
Autograder behaviorClassroom grading panel, PR checks, and Actions logsOn relevant challenge eventsTrigger known pass and known fail for each autograded challengeFailing scenarios are understandable and pass after correct fix
Chapter content consistencyMarkdown files under docsDuring curriculum review phase before sign-offExecute full chapter and appendix checklistAll required docs reviewed and discrepancies logged
Challenge coverage completenessChallenge tracking table in this runbookDuring student journey executionFill all rows for 1-16 and A-ENo challenge row is left blank or untracked
+

Reading Order for Operators

+

Read these files in this exact order before executing the runbook.

+
    +
  1. REGISTRATION-QUICKSTART.md
    2. +
  2. REGISTRATION-ADMIN.md
    3. +
  3. classroom/README.md
    4. +
  4. admin/classroom/autograding-setup.md
    5. +
  5. classroom/HUMAN_TEST_MATRIX.md
    6. +
  6. docs/CHALLENGES.md
    7. +
+

Reading completion rule:

+
    +
  1. Do not begin Phase 0 until all files above are opened and skimmed for current cohort context.
    2. +
  2. Log "reading complete" with timestamp in QA notes.
    3. +
+

Why this matters:

+
    +
  • Most setup errors come from skipping source-of-truth docs before execution.
    • +
+

Pre-Flight Local Validation (Non-Podcast)

+

Run these from repository root before live environment QA.

+
npm run test:automation
+npm run build:html
+git diff --check
+
+

Pass criteria:

+
    +
  • Automation tests pass.
    • +
  • HTML build completes.
    • +
  • No unresolved conflict markers or whitespace check failures.
    • +
+

Local unit-test evidence requirements

+

Record and publish local test evidence under admin/qa-readiness.

+

Minimum evidence:

+
    +
  • Test command used.
    • +
  • Total tests, pass count, fail count.
    • +
  • Any failing tests and remediation actions.
    • +
  • Residual risk statement for hosted GitHub behavior not proven by local tests.
    • +
+

Recommended report format:

+ +

No-go rule:

+
    +
  • If local readiness tests fail, do not proceed to template deployment or classroom assignment setup.
    • +
+

Execution procedure:

+
    +
  1. Run commands in listed order from repository root.
    2. +
  2. Capture terminal output snippets for each command.
    3. +
  3. If any command fails, record failure cause and remediation attempt.
    4. +
  4. Re-run failed command after remediation and capture final outcome.
    5. +
+

Why this matters:

+
    +
  • Pre-flight catches local defects before they become live Classroom failures.
    • +
+

Phase 0 - Registration System Deployment Gate (Admin Side)

+

This phase is mandatory. Do not run registration QA tests until deployment/configuration is complete.

+

Step 0.1 Deploy registration issue form and workflow prerequisites

+

Goal: ensure the registration intake system is deployed and configured for this course cohort.

+
    +
  1. Confirm registration issue form template exists and is current:
      +
    • .github/ISSUE_TEMPLATE/workshop-registration.yml
      • +
    +
    2. +
  2. Confirm registration workflow exists and is enabled:
      +
    • .github/workflows/registration.yml
      • +
    +
    3. +
  3. Confirm required labels exist in repository:
      +
    • registration
      • +
    • duplicate
      • +
    • waitlist
      • +
    +
    4. +
  4. Confirm repository Actions are enabled for this repository.
    5. +
+

Pass criteria:

+
    +
  • Issue form template is present and selectable from "New issue".
    • +
  • Registration workflow is enabled and visible in Actions.
    • +
  • Required labels exist and are usable.
    • +
+

Step 0.2 Deploy optional registration-to-classroom automation settings

+

Goal: enable automatic org invite and assignment-link injection in registration confirmation comments.

+
    +
  1. In repository settings, configure secret:
      +
    • CLASSROOM_ORG_ADMIN_TOKEN
      • +
    +
    2. +
  2. In repository settings, configure variables:
      +
    • CLASSROOM_ORG
      • +
    • CLASSROOM_DAY1_ASSIGNMENT_URL
      • +
    • CLASSROOM_DAY2_ASSIGNMENT_URL
      • +
    +
    3. +
  3. Re-open each value and verify no leading or trailing spaces.
    4. +
+

Pass criteria:

+
    +
  • Secret and variables are present with correct values.
    • +
  • Configuration aligns with REGISTRATION-ADMIN.md.
    • +
+

Step 0.3 Registration deployment smoke check

+

Goal: validate deployed registration system can execute at least one full workflow run.

+
    +
  1. Submit one test registration issue from a non-admin test account.
    2. +
  2. Confirm Registration - Welcome & CSV Export workflow completes.
    3. +
  3. Confirm welcome comment posts and registration label is applied.
    4. +
  4. If classroom automation is configured, confirm org invite status and assignment links appear.
    5. +
+

Pass criteria:

+
    +
  • Registration workflow executes successfully end to end.
    • +
  • Output comment/labels match deployed configuration.
    • +
+

Phase 1 - Registration System QA (Admin Side)

+

Step 1. Verify public registration entry path

+
    +
  1. Open REGISTER.md and confirm the registration link points to the issue form template with workshop-registration.yml.
    2. +
  2. Open the rendered registration page and activate the registration form link.
    3. +
  3. Confirm the issue form opens with [REGISTER] in the title.
    4. +
  4. Confirm the page communicates that registration issues are public.
    5. +
+

Pass criteria:

+
    +
  • Registration link opens correctly.
    • +
  • Registration issue title is prefilled with [REGISTER].
    • +
  • Public visibility warning is present.
    • +
+

Step 2. Configure registration automation for classroom handoff

+

Use REGISTRATION-QUICKSTART.md for fast entry and REGISTRATION-ADMIN.md for full details.

+
    +
  1. Create or verify an admin token that can manage organization invitations.
    2. +
  2. In repository settings, add secret CLASSROOM_ORG_ADMIN_TOKEN.
    3. +
  3. In repository settings, set variables:
      +
    • CLASSROOM_ORG
      • +
    • CLASSROOM_DAY1_ASSIGNMENT_URL
      • +
    • CLASSROOM_DAY2_ASSIGNMENT_URL
      • +
    +
    4. +
  4. Save and re-open each setting to confirm there are no leading or trailing spaces.
    5. +
+

Pass criteria:

+
    +
  • Secret exists and is scoped correctly.
    • +
  • All 3 variables exist and values are correct.
    • +
+

Step 3. Execute registration happy-path test

+

Use the non-admin test student account.

+
    +
  1. Submit the registration issue form once.
    2. +
  2. Wait for Registration - Welcome & CSV Export workflow to complete.
    3. +
  3. Confirm the issue receives a welcome comment.
    4. +
  4. Confirm the welcome comment includes:
      +
    • Zoom registration information.
      • +
    • Day 1 and Day 2 assignment links (if variables are set).
      • +
    • Organization invitation status when classroom org automation is active.
      • +
    +
    5. +
  5. Confirm registration label is applied.
    6. +
+

Pass criteria:

+
    +
  • Workflow succeeds.
    • +
  • Comment content is complete and accurate.
    • +
  • registration label exists on the issue.
    • +
+

Step 4. Execute duplicate and waitlist tests

+
    +
  1. Submit a second registration issue from the same test account.
    2. +
  2. Confirm workflow marks the issue duplicate and closes it with guidance to the original issue.
    3. +
  3. For waitlist behavior, use a controlled test strategy:
      +
    • Preferred: run in a staging copy where capacity can be reached safely.
      • +
    • Alternative: dry-run logic review from .github/workflows/registration.yml and verify conditions with maintainers.
      • +
    +
    4. +
  4. Confirm waitlist message and waitlist label behavior in the chosen test environment.
    5. +
+

Pass criteria:

+
    +
  • Duplicate submission closes with duplicate guidance.
    • +
  • Waitlist path and label behavior are validated.
    • +
+

Step 5. Verify CSV export and roster sync outputs

+
    +
  1. Open the workflow run artifacts and download registration-data.
    2. +
  2. Confirm CSV includes expected columns and test user row.
    3. +
  3. Verify .github/data/student-roster.json is updated by workflow with non-PII operational fields.
    4. +
  4. Optionally trigger manual rebuild:
    5. +
+
gh workflow run registration.yml -R community-access/git-going-with-github
+
+

Pass criteria:

+
    +
  • CSV artifact is present and parseable.
    • +
  • Roster sync commit appears only when data changed.
    • +
+

Phase 2 - Learning Room Template Deployment Gate (Admin Side)

+

This phase is mandatory. Do not create Classroom assignments until this gate is complete.

+

Step 6. Sync local Learning Room source into GitHub template repository

+

Goal: ensure Community-Access/learning-room-template reflects the latest source from learning-room/.

+

Run from repository root:

+
scripts/classroom/Prepare-LearningRoomTemplate.ps1 -Owner Community-Access -TemplateRepo learning-room-template
+
+

What to expect:

+
    +
  1. Script verifies GitHub CLI auth.
    2. +
  2. Script ensures template repository settings (template mode and Actions permissions where allowed).
    3. +
  3. Script creates a sync branch and PR if changes exist.
    4. +
  4. If no changes exist, script reports no template changes to commit.
    5. +
+

Where to verify:

+
    +
  • Community-Access/learning-room-template pull requests list.
    • +
  • Template repository Actions/settings page.
    • +
+

Pass criteria:

+
    +
  • Template sync PR exists and is merged to main, or script reports no changes required.
    • +
  • Template repository remains configured as a template repository.
    • +
  • Template repository default branch is main and visible in repository settings.
    • +
+

Step 7. Validate published template with smoke repository

+

Goal: prove that new repos created from the template include required workflows/templates and can trigger challenge progression.

+

Run from repository root:

+
scripts/classroom/Test-LearningRoomTemplate.ps1 -Owner Community-Access -TemplateRepo learning-room-template
+
+

What to expect:

+
    +
  1. Script creates a temporary private smoke repo from the template.
    2. +
  2. Script checks key files exist (student progression workflow, challenge template, progression script).
    3. +
  3. Script triggers Challenge 1 workflow dispatch.
    4. +
  4. Script deletes smoke repo unless -KeepSmokeRepo is specified.
    5. +
+

Where to verify:

+
    +
  • Smoke repo creation/deletion in GitHub repos list.
    • +
  • Workflow run history and issue creation in smoke repo when retained.
    • +
+

Pass criteria:

+
    +
  • Smoke repo creation succeeds from template.
    • +
  • Required files exist in smoke repo.
    • +
  • Challenge 1 workflow dispatch succeeds.
    • +
  • Smoke repo validates workflow inventory:
      +
    • pr-validation-bot.yml
      • +
    • content-validation.yml
      • +
    • student-progression.yml
      • +
    • skills-progression.yml
      • +
    • autograder-conflicts.yml
      • +
    • autograder-local-commit.yml
      • +
    • autograder-template.yml
      • +
    • autograder-capstone.yml
      • +
    +
    • +
+

Step 8. Prove template freshness (latest release content is live)

+

Goal: confirm that newly created repositories are generated from the latest deployed template content, not stale template state.

+
    +
  1. Keep the smoke repository (-KeepSmokeRepo) or create another temporary smoke repo from template.
    2. +
  2. Open the merged template sync PR from Step 6.
    3. +
  3. Select at least 3 files changed in that PR, including at least:
      +
    • one workflow file,
      • +
    • one issue template file,
      • +
    • one docs or script file.
      • +
    +
    4. +
  4. Verify those exact file changes are present in the smoke repository.
    5. +
  5. Record evidence links in your QA notes.
    6. +
+

Pass criteria:

+
    +
  • Evidence shows smoke repo content matches the latest merged template sync changes.
    • +
  • No stale-file mismatch is found.
    • +
+

Step 9. Optional comprehensive harness check

+

For deeper verification, run:

+
scripts/classroom/Invoke-LearningRoomEndToEndTest.ps1 -SelfTest
+
+

Use full end-to-end mode when preparing major cohort launches or after significant automation updates.

+

Phase 3 - Classroom Deployment QA (Admin Side)

+

Step 10. Create classroom and import roster

+

Use classroom/README.md Steps 1 and 2.

+
    +
  1. Create a new classroom in Community-Access.
    2. +
  2. Name it using Git Going - [Cohort Name] - [Month Year].
    3. +
  3. Import roster using classroom/roster-template.csv.
    4. +
  4. Confirm test student appears in roster.
    5. +
+

Pass criteria:

+
    +
  • Classroom exists and is accessible to facilitators.
    • +
  • Roster import succeeds with expected usernames.
    • +
+

Step 11. Create Day 1 assignment exactly

+

Use classroom/assignment-day1-you-belong-here.md and admin/classroom/day1-assignment-copy-paste.md.

+
    +
  1. Create assignment with title You Belong Here.
    2. +
  2. Set type Individual.
    3. +
  3. Set visibility Private.
    4. +
  4. Select template Community-Access/learning-room-template.
    5. +
  5. Set Grant students admin access to No.
    6. +
  6. Set Enable feedback pull requests to Yes.
    7. +
  7. Paste Day 1 assignment description content.
    8. +
  8. Add Day 1 autograding entries from admin/classroom/autograding-setup.md.
    9. +
  9. Confirm Day 1 has 4 tests and total 50 points.
    10. +
  10. Save assignment and copy invite link.
    11. +
+

Pass criteria:

+
    +
  • Day 1 settings match source files exactly.
    • +
  • Test count and points are correct.
    • +
  • Feedback pull request is enabled and visible in assignment configuration.
    • +
+

Step 12. Create Day 2 assignment exactly

+

Use classroom/assignment-day2-you-can-build-this.md and admin/classroom/day2-assignment-copy-paste.md.

+
    +
  1. Create assignment with title You Can Build This.
    2. +
  2. Apply same base settings as Day 1 (individual, private, no admin access, feedback PR enabled).
    3. +
  3. Paste Day 2 assignment description content.
    4. +
  4. Add Day 2 autograding entries from admin/classroom/autograding-setup.md.
    5. +
  5. Confirm Day 2 has 6 tests and total 75 points.
    6. +
  6. Save assignment and copy invite link.
    7. +
+

Pass criteria:

+
    +
  • Day 2 settings match source files exactly.
    • +
  • Test count and points are correct.
    • +
  • Feedback pull request is enabled and visible in assignment configuration.
    • +
+

Step 13. Connect assignment URLs back to registration automation

+
    +
  1. Add or update repository variables:
      +
    • CLASSROOM_DAY1_ASSIGNMENT_URL
      • +
    • CLASSROOM_DAY2_ASSIGNMENT_URL
      • +
    +
    2. +
  2. Re-run one registration test issue (new test account or controlled case).
    3. +
  3. Confirm both links appear in welcome comment.
    4. +
+

Pass criteria:

+
    +
  • Registration confirmation comment now includes both assignment URLs.
    • +
+

Phase 4 - Test Student Acceptance and Seeding (Bridge from Admin to Student)

+

Step 14. Test student accepts Day 1 and Day 2 invites

+

Use the test student account.

+
    +
  1. Open Day 1 invite URL.
    2. +
  2. Accept assignment and wait for repo creation.
    3. +
  3. Record Day 1 test repo URL.
    4. +
  4. Open Day 2 invite URL.
    5. +
  5. Accept assignment and wait for repo creation.
    6. +
  6. Record Day 2 test repo URL.
    7. +
+

Pass criteria:

+
    +
  • Two private repos are created and visible in classroom dashboard.
    • +
+

Step 15. Seed initial challenges and peer simulation

+

Run commands from repository root.

+
scripts/classroom/Seed-LearningRoomChallenge.ps1 -Repository Community-Access-Classroom/learning-room-test-student-day1 -Challenge 1 -Assignee test-student
+scripts/classroom/Seed-PeerSimulation.ps1 -Repository Community-Access-Classroom/learning-room-test-student-day1 -StudentUsername test-student
+scripts/classroom/Seed-LearningRoomChallenge.ps1 -Repository Community-Access-Classroom/learning-room-test-student-day2 -Challenge 10 -Assignee test-student
+scripts/classroom/Seed-PeerSimulation.ps1 -Repository Community-Access-Classroom/learning-room-test-student-day2 -StudentUsername test-student
+
+

If you use different repository names, replace values accordingly.

+

Pass criteria:

+
    +
  • Challenge 1 appears in Day 1 repo.
    • +
  • Challenge 10 appears in Day 2 repo.
    • +
  • Peer simulation issues and PR exist in both repos.
    • +
+

Phase 5 - Curriculum Content QA (Walk every required chapter and appendix)

+

This phase is required. Do not skip this phase even if challenge automation is passing.

+

Step 16. Execute full chapter and appendix walkthrough

+

For each file listed below, open it and verify:

+
    +
  1. Instructions are accurate for the current Classroom model.
    2. +
  2. Links resolve or are intentionally marked as practice targets.
    3. +
  3. Accessibility language is actionable and not visual-only.
    4. +
  4. Challenge references align with docs/CHALLENGES.md.
    5. +
+

Use this per-file verification routine before checking each box:

+
    +
  1. Open the file and read it once top to bottom without editing.
    2. +
  2. Re-read while validating the 4 checks above and capture any defects in your QA notes.
    3. +
  3. If no defect is found, mark the checkbox complete immediately.
    4. +
  4. If a defect is found, leave checkbox open until defect is logged with owner and due date.
    5. +
+

Why this matters:

+
    +
  • This prevents "skim and check" behavior that misses broken learner paths.
    • +
  • It ensures every completed checkbox represents a defensible QA review, not just a visual pass.
    • +
+

Track completion using this checklist.

+

Core learner docs:

+ +

Core chapters:

+ +

Appendices:

+ +

Phase 4 pass criteria:

+
    +
  • Every listed file has been reviewed and marked complete.
    • +
  • Any doc defects are logged with owner and due date.
    • +
+

Step 17. Validate supporting content outside chapters

+

Review the following content surfaces because they directly affect learner and facilitator experience.

+

Use this verification routine for each section below (Root docs, Classroom docs, Learning Room automation docs):

+
    +
  1. Open all files in the section and compare wording for the same workflow concepts.
    2. +
  2. Confirm setup steps, command names, and expected outcomes match current automation behavior.
    3. +
  3. Confirm links between docs resolve and point to the intended destination.
    4. +
  4. Mark each file checkbox only after you either confirm consistency or log a specific defect.
    5. +
+

Why this matters:

+ +

Pass criteria:

+
    +
  • Supporting docs are consistent with chapter guidance and current automation behavior.
    • +
  • Any cross-document contradictions are logged as defects.
    • +
+

Phase 6 - Student Journey QA (Walk every path as a student)

+

Use classroom/HUMAN_TEST_MATRIX.md as your execution baseline and record evidence for each challenge.

+

Phase execution rule:

+
    +
  1. Run student journey checks in challenge order unless explicitly validating a failure-mode branch.
    2. +
  2. For each challenge, capture issue URL, evidence comment URL, and workflow/check outcome.
    3. +
  3. Update the Challenge Tracking Log row immediately after each challenge completes.
    4. +
  4. If progression fails, stop sequence and resolve before moving to next challenge.
    5. +
+

Why this matters:

+
    +
  • Ordered execution is required to validate progression automation and student experience continuity.
    • +
+

Student pre-read sequence before challenge execution

+

Have the tester read in this order:

+
    +
  1. docs/get-going.md
    2. +
  2. docs/00-pre-workshop-setup.md
    3. +
  3. docs/04-the-learning-room.md
    4. +
  4. docs/CHALLENGES.md
    5. +
+

Day 1 challenge walkthrough (Challenges 1 to 9)

+

For each challenge issue, perform this pattern:

+
    +
  1. Open challenge issue.
    2. +
  2. Complete required actions.
    3. +
  3. Post evidence comment.
    4. +
  4. Close issue.
    5. +
  5. Confirm next challenge issue appears.
    6. +
+

Challenge-specific checks:

+
    +
  1. Challenge 1: verify orientation tasks and next challenge creation.
    2. +
  2. Challenge 2: create a clear issue from docs/welcome.md TODO.
    3. +
  3. Challenge 3: comment on peer simulation issue and include mention.
    4. +
  4. Challenge 4: create learn/<username> branch.
    5. +
  5. Challenge 5: commit real content change with descriptive message.
    6. +
  6. Challenge 6: open PR with Closes #N and validate Aria response.
    7. +
  7. Challenge 7: run conflict seeding and resolve conflict markers.
    8. +
  8. Challenge 8: submit culture reflection evidence.
    9. +
  9. Challenge 9: merge PR and confirm linked issue closes.
    10. +
+

Run merge conflict setup when Challenge 7 is reached:

+
scripts/classroom/Start-MergeConflictChallenge.ps1 -Repository Community-Access-Classroom/learning-room-test-student-day1 -StudentBranch learn/test-student
+
+

Day 1 pass criteria:

+
    +
  • Progression works across all nine challenges.
    • +
  • Aria feedback appears on test PRs.
    • +
  • Challenge 7 conflict-marker checks fail before fix and pass after fix.
    • +
+

Day 2 challenge walkthrough (Challenges 10 to 16)

+

Use the same five-step issue pattern for each challenge.

+

Challenge-specific checks:

+
    +
  1. Challenge 10: clone locally, branch, edit, commit, push, and verify local commit workflow.
    2. +
  2. Challenge 11: open PR from Day 2 local branch and verify feedback.
    3. +
  3. Challenge 12: complete structured review on peer simulation PR.
    4. +
  4. Challenge 13: capture Copilot suggestion and student judgment.
    5. +
  5. Challenge 14: create custom non-challenge issue template with required fields and verify workflow.
    6. +
  6. Challenge 15: inspect accessibility agents and capture findings.
    7. +
  7. Challenge 16: fork Community-Access/accessibility-agents, create agent file with frontmatter, responsibilities, and guardrails, then open cross-fork PR.
    8. +
+

Day 2 pass criteria:

+
    +
  • Progression works from 10 through 16.
    • +
  • Autograders for 10, 14, and 16 provide useful pass/fail feedback.
    • +
  • Capstone evidence is complete and reviewable.
    • +
+

Student-visible expected state map (required cross-check)

+

Use this section to confirm what students should see, where they should see it, and what artifacts should exist after each stage.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
StageWhere student looksWhat student should seeExpected artifacts
After assignment acceptanceRepository home and Issues tabPrivate Learning Room repository created from templateStarter docs (docs/welcome.md, docs/keyboard-shortcuts.md, docs/setup-guide.md), workflows, issue templates
After initial seedingIssues tabCorrect starting challenge issue appears (Challenge 1 or Challenge 10)Assigned challenge issue with clear instructions and evidence prompt
During Day 1 PR flow (Ch 4-6)Branch selector, Pull requests, ActionsStudent branch exists, PR open, bot feedback appearsBranch learn/<username> or equivalent, PR with Closes #N, Aria validation comment
During merge conflict (Ch 7)PR conversation/files, Checks tabConflict state visible, then resolvedConflict markers present pre-fix, removed post-fix, conflict check transitions to pass
During Day 2 local flow (Ch 10-11)Local clone and remote PRLocal commit/push reflected in PR and checksNon-default-branch commit visible in history and checks
During template challenge (Ch 14)File tree and PR checksCustom template exists and passes required-field checksNew .github/ISSUE_TEMPLATE/*.yml file with name and description
During capstone (Ch 16)Fork repo and capstone PRCross-fork contribution path works with required structureAgent file with frontmatter, responsibilities, guardrails; PR evidence
Bonus pathIssue templates and evidence commentsBonus templates are available and usableBonus issue evidence and status recorded in tracker
+

Pass criteria:

+
    +
  • Student-visible state is confirmed at each stage above.
    • +
  • Any mismatch between expected and observed student experience is logged as a defect.
    • +
+

Bonus path walkthrough (A to E)

+

Bonus challenges are optional for students, but QA tracking is required for every bonus challenge.

+
    +
  1. Open each bonus template.
    2. +
  2. Confirm instructions are understandable and actionable.
    3. +
  3. Track completion status for each bonus challenge A to E.
    4. +
  4. If a bonus challenge is not fully executed, record why and what validated the path.
    5. +
+

Pass criteria:

+
    +
  • All bonus challenges A to E have explicit status and notes.
    • +
  • No bonus challenge is left untracked.
    • +
+

Challenge Tracking Log (Required)

+

Use this tracker while executing Phase 5. Every row must be completed.

+

Row completion standard:

+
    +
  1. Status must be one of Pass, Fail, or Deferred.
    2. +
  2. Evidence link must point to issue, PR, workflow run, or equivalent proof.
    3. +
  3. Notes must include remediation or deferral rationale when status is not Pass.
    4. +
+

Why this matters:

+
    +
  • Complete row data is required for defensible release decisions and post-run audits.
    • +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ChallengeTitleStatus (Pass/Fail/Deferred)Evidence linkNotes
1Find Your Way Around
2File Your First Issue
3Join the Conversation
4Branch Out
5Make Your Mark
6Open Your First Pull Request
7Survive a Merge Conflict
8The Culture Layer
9Merge Day
10Go Local
11Open a Day 2 PR
12Review Like a Pro
13AI as Your Copilot
14Template Remix
15Meet the Agents
16Build Your Agent (Capstone)
Bonus AImprove an Existing Agent
Bonus BDocument Your Journey
Bonus CCreate a Group Challenge
Bonus DNotification Mastery
Bonus EExplore Git History Visually
+

Challenge Reliability and Failure-Mode Coverage (Required)

+

Do not mark the challenge system reliable until this section is completed.

+

Reliability test personas

+

Run challenge validation with at least these personas:

+
    +
  • Persona A: Day 1 + Day 2 student path (full path through 1-16).
    • +
  • Persona B: Day-2-only student path (starts at Challenge 10).
    • +
+

Required variation categories

+

For each applicable challenge, test and document all categories below:

+
    +
  1. Happy path completion.
    2. +
  2. Common student error path.
    3. +
  3. Recovery path after feedback.
    4. +
  4. Automation latency/idempotency behavior (reruns, duplicate events, delayed comments).
    5. +
+

Variation matrix by challenge family

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Challenge familyMinimum failure/variation scenarios to testPass criteria
1-3 orientation and issue flowMissing evidence comment, evidence posted in wrong issue, issue closed without evidence, delayed bot response on mentionStudent can recover without facilitator-only intervention; instructions remain clear
4-6 branch/commit/PR flowWrong branch, commit to main, PR missing Closes #N, weak PR body, duplicate PR attemptsBot/autograder guidance is actionable and student can fix to pass
7 conflict flowConflict markers left in file, partial resolution, wrong file resolved, reintroducing markers on next commitFails when unresolved, passes after true resolution, feedback explains next step
8-9 culture/merge flowReflection too vague, merge blocked by checks, PR approved but not mergeable, issue not auto-closingStudent can complete with clear guidance and accurate merge outcome
10-11 local workflowLocal auth failure, push to wrong remote/branch, no new commit, PR from wrong baseFailure mode is discoverable and recoverable with provided guidance
12 review workflowReview left as comment only, no actionable feedback, review submitted on wrong PRChallenge guidance clarifies expectations and evidence remains evaluable
13 Copilot evidenceMissing prompt/evaluation details, copied output without judgment, evidence too shallowStudent can revise evidence and meet evaluation criteria
14 template workflowTemplate file wrong folder/name, missing name, missing description, invalid YAMLAutograder fails correctly and passes only after true fix
15 agent explorationSuperficial exploration notes, wrong repo referenced, no evidence of actual inspectionChallenge remains completable with clear evidence requirements
16 capstoneMissing frontmatter, missing responsibilities/guardrails, PR to wrong repo, incomplete cross-fork setupAutograder/checklist catches gaps and student can recover to complete
Bonus A-EStudent starts bonus without prerequisites, partial completion, alternate evidence formatEach bonus has documented pass/fail/deferred outcome and rationale
+

Cross-cutting failure modes (must be tested at least once)

+
    +
  • Bot comment delay greater than expected window.
    • +
  • Workflow rerun without creating duplicate progression issues.
    • +
  • Student posts evidence in wrong place then corrects it.
    • +
  • Autograder false-negative suspicion escalated and resolved with facilitator override process.
    • +
  • Permission/access prompt encountered and resolved (student and facilitator perspectives).
    • +
+

Reliability gate pass criteria

+
    +
  • Every challenge (1-16 and Bonus A-E) has at least one documented happy path and one documented variation/failure scenario.
    • +
  • Recovery steps are validated, not assumed.
    • +
  • No critical failure path requires hidden facilitator knowledge outside documented guidance.
    • +
+

Student recovery and reset playbook (required)

+

If a student repository is corrupted, use this escalation path.

+

Level 1: Student self-recovery (preferred)

+
    +
  1. Re-open challenge instructions and compare against required target file.
    2. +
  2. Use PR diff to undo accidental changes.
    3. +
  3. Restore missing text from template references in challenge guidance.
    4. +
  4. Push a corrective commit and re-run checks.
    5. +
+

Use when:

+
    +
  • Student changed only small sections in expected challenge files.
    • +
+

Level 2: Facilitator-assisted file restore (safe branch+PR)

+

Use the recovery script to restore baseline files from Community-Access/learning-room-template into a student repo on a recovery branch.

+

Script:

+
scripts/classroom/Restore-LearningRoomFiles.ps1 -StudentRepository Community-Access-Classroom/learning-room-studentname -Profile core-day1 -OpenPullRequest
+
+

Profiles:

+
    +
  • core-day1 restores Day 1 starter docs.
    • +
  • core-day2 restores Day 2 sample docs.
    • +
  • automation-core restores workflow files.
    • +
  • all-core restores all above.
    • +
  • custom restores explicit paths provided via -Paths.
    • +
+

Use when:

+
    +
  • A challenge file, sample file, or workflow file was accidentally overwritten or deleted.
    • +
+

Level 3: Repository re-provision fallback

+

If corruption is broad and recovery branch approach is not sufficient:

+
    +
  1. Export evidence links needed for grading history.
    2. +
  2. Remove student assignment entry in Classroom (if policy allows).
    3. +
  3. Re-invite student to assignment to generate a fresh repository.
    4. +
  4. Re-seed appropriate challenge and peer simulation artifacts.
    5. +
  5. Document mapping from old repo to replacement repo in facilitator notes.
    6. +
+

Use when:

+
    +
  • Student repo is not reasonably recoverable with targeted file restores.
    • +
+

Recovery gate pass criteria

+
    +
  • At least one Level 2 recovery test is completed in QA and documented.
    • +
  • Facilitators can perform targeted restore without editing files manually in GitHub UI.
    • +
  • Recovery actions preserve auditability through branch/PR evidence.
    • +
+

Phase 7 - Workflow and Automation Validation Matrix

+

Use this matrix as your quick final automation check.

+

Matrix execution procedure:

+
    +
  1. Work row by row.
    2. +
  2. Trigger or locate the required event for each component.
    3. +
  3. Verify expected behavior in the stated location.
    4. +
  4. Record one evidence link per row.
    5. +
  5. Mark row complete only when observed behavior matches expected experience.
    6. +
+

Why this matters:

+
    +
  • The matrix is the final integration proof that automation is functioning as designed.
    • +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Automation componentWhat to verifyWhere to verifyTrigger timingExpected experience
registration.yml welcome jobNew registration handlingRegistration issue comment + labels + Actions runOn issue open with [REGISTER]Welcome comment posted, registration label applied, no manual intervention
registration.yml duplicate logicDuplicate handlingDuplicate issue thread + labels + closed stateOn second submission by same userDuplicate message references original and issue auto-closes
registration.yml waitlist logicCapacity full behaviorRegistration issue comment + waitlist labelWhen threshold reached in controlled testWaitlist message and label applied
registration.yml CSV exportRegistration data artifactActions artifactsEvery registration run or manual dispatchregistration-data artifact is available and current
registration.yml roster syncNon-PII roster update.github/data/student-roster.json and workflow commitEvery registration run or manual dispatchRoster updates only when changed and no PII stored
pr-validation-bot.ymlPR structure and guidance checksPR comments + ActionsPR open/edit/sync/review eventsValidation comment appears and updates in place
content-validation.ymlLink/markdown/accessibility checksPR checks/comments + Actions logsPR open/edit/syncClear actionable findings tied to changed files
student-progression.ymlChallenge unlock sequenceIssues tab + Actions logsIssue close and workflow dispatchNext challenge issue appears with correct sequence
skills-progression.ymlSkill/achievement feedbackPR comments + ActionsPR mergeAchievement/progress feedback posts without failure
autograder-conflicts.ymlConflict marker detection for Ch07Actions checks + PR statusPR open/edit for conflict scenarioFails before fix, passes after marker removal
autograder-local-commit.ymlLocal commit validation for Ch10Actions checks + PR/status outputPush/PR for Ch10 scenarioDetects non-default-branch commit
autograder-template.ymlIssue template validation for Ch14Actions checks + PR/status outputTemplate challenge workflow triggerFails missing fields, passes with name and description
autograder-capstone.ymlAgent structure validation for Ch16Actions checks + PR/status outputCapstone PR eventsValidates frontmatter, responsibilities, and guardrails
Seed-LearningRoomChallenge.ps1Challenge seed operationIssues tab + workflow run historyOn script executionTarget challenge appears and assignment is correct
Seed-PeerSimulation.ps1Peer simulation artifactsIssues + PR list + branch listOn script executionPeer simulation issues and PR appear as expected
Start-MergeConflictChallenge.ps1Merge conflict scenario creationStudent PR conflict state + checksOn script execution during Ch07Conflict becomes visible and resolvable
Test-LearningRoomTemplate.ps1Template readiness scanScript output + remediation notesBefore assignment publish and after updatesReports readiness state and clear gaps
Prepare-LearningRoomTemplate.ps1Template preparation operationsScript output + repository checksBefore go-live if prep neededRequired template prep completes without hidden failures
Invoke-LearningRoomEndToEndTest.ps1Full-scripted QA helper pathScript output and referenced artifactsOptional preflight or regression validationEnd-to-end script executes expected checks
Add-AutograderSafeguards.ps1 and Fix-AutograderComments.ps1Autograder hardening utilitiesScript output + workflow behaviorAs needed during defects/fixesSafeguards/comments behavior aligns with expected feedback quality
+

Phase 8 - Final Sign-Off (Podcast-Excluded Release Gate)

+

Use this checklist for final decision. For every item, complete the listed verification steps and record evidence before checking the box.

+
    +

  • +Registration intake path tested from public page to welcome comment. + Verification steps:

    +
      +
    1. Execute Phase 1 Step 1 and Step 3 with a test registration.
      2. +
    2. Capture the public entry point, issue creation, and final welcome comment evidence.
      3. +
    3. Confirm labels and comment content match expected behavior in the QA Validation Contract. + Why this matters: this proves the first learner touchpoint works end to end.
      4. +
    +
    • +

  • +Registration duplicate handling validated. + Verification steps:

    +
      +
    1. Execute Phase 1 Step 4 duplicate scenario.
      2. +
    2. Confirm duplicate issue closes automatically and references the original.
      3. +
    3. Record issue links and labels in QA notes. + Why this matters: duplicate control prevents noisy intake and manual cleanup overhead.
      4. +
    +
    • +

  • +Registration CSV and roster sync validated. + Verification steps:

    +
      +
    1. Execute Phase 1 Step 5.
      2. +
    2. Download registration-data artifact and verify the expected test row.
      3. +
    3. Confirm roster sync updates only when underlying data changes. + Why this matters: operations teams depend on accurate roster exports for cohort management.
      4. +
    +
    • +

  • +Learning Room template sync to GitHub template repository validated. + Verification steps:

    +
      +
    1. Execute Phase 2 Step 6.
      2. +
    2. Confirm sync PR merged (or no-change outcome) and template repo settings remain correct.
      3. +
    3. Record PR link or no-change script output. + Why this matters: stale template state breaks downstream assignments even when source repo is correct.
      4. +
    +
    • +

  • +Template smoke repository validation completed from latest template state. + Verification steps:

    +
      +
    1. Execute Phase 2 Step 7.
      2. +
    2. Confirm smoke repo creation, required file inventory, and seed dispatch behavior.
      3. +
    3. Record script output and retained evidence links. + Why this matters: this is the fastest proof that template consumers get runnable automation.
      4. +
    +
    • +

  • +Template freshness proof completed against latest merged sync PR. + Verification steps:

    +
      +
    1. Execute Phase 2 Step 8.
      2. +
    2. Compare at least three changed files from sync PR to smoke repo content.
      3. +
    3. Log exact file comparisons in QA notes. + Why this matters: confirms new cohorts are not launched from outdated template snapshots.
      4. +
    +
    • +

  • +Day 1 assignment configured and validated. + Verification steps:

    +
      +
    1. Execute Phase 3 Step 11.
      2. +
    2. Verify assignment settings, description, autograder count, and points.
      3. +
    3. Store screenshot of final assignment configuration page. + Why this matters: Day 1 misconfiguration creates immediate learner friction and grading drift.
      4. +
    +
    • +

  • +Day 2 assignment configured and validated. + Verification steps:

    +
      +
    1. Execute Phase 3 Step 12.
      2. +
    2. Verify assignment settings, description, autograder count, and points.
      3. +
    3. Store screenshot of final assignment configuration page. + Why this matters: Day 2 challenge flow and capstone checks depend on exact assignment setup.
      4. +
    +
    • +

  • +Registration form template and required labels validated. + Verification steps:

    +
      +
    1. Execute Phase 0 Step 0.1 and re-check before sign-off.
      2. +
    2. Confirm workshop-registration.yml is current and selectable.
      3. +
    3. Confirm labels registration, duplicate, and waitlist exist and are active. + Why this matters: the registration workflow cannot route correctly without these baseline objects.
      4. +
    +
    • +

  • +Test student accepted both assignments and repos created. + Verification steps:

    +
      +
    1. Execute Phase 4 Step 14.
      2. +
    2. Confirm two private repos are created for Day 1 and Day 2.
      3. +
    3. Record both repository URLs in completion notes. + Why this matters: acceptance and repo provisioning are required before challenge QA can begin.
      4. +
    +
    • +

  • +Full chapter and appendix walkthrough completed and tracked. + Verification steps:

    +
      +
    1. Execute Phase 5 Step 16 using the per-file verification routine.
      2. +
    2. Ensure every required chapter and appendix checkbox is either complete or tied to a logged defect.
      3. +
    3. Confirm no file in the required list is left unreviewed. + Why this matters: curriculum defects can invalidate otherwise healthy automation.
      4. +
    +
    • +

  • +Supporting non-chapter content walkthrough completed and tracked. + Verification steps:

    +
      +
    1. Execute Phase 5 Step 17 using the section verification routine.
      2. +
    2. Resolve or log all cross-document inconsistencies.
      3. +
    3. Confirm all supporting-doc checkboxes are complete or defect-linked. + Why this matters: learners rely on these docs during setup and troubleshooting.
      4. +
    +
    • +

  • +Challenge 1 and Challenge 10 seeding validated. + Verification steps:

    +
      +
    1. Execute Phase 4 Step 15.
      2. +
    2. Confirm seeded issues appear in Day 1 and Day 2 test repos.
      3. +
    3. Capture issue links for both seeded starting points. + Why this matters: seeding failures block both student journey entry paths.
      4. +
    +
    • +

  • +Full Day 1 student path (1 to 9) completed. + Verification steps:

    +
      +
    1. Execute Phase 6 Day 1 walkthrough across Challenges 1-9.
      2. +
    2. Confirm progression behavior after each issue closure.
      3. +
    3. Fill Day 1 rows in Challenge Tracking Log with evidence links. + Why this matters: Day 1 is the foundational workflow and must be dependable for all learners.
      4. +
    +
    • +

  • +Full Day 2 student path (10 to 16) completed. + Verification steps:

    +
      +
    1. Execute Phase 6 Day 2 walkthrough across Challenges 10-16.
      2. +
    2. Confirm Day 2 autograder behavior for 10, 14, and 16.
      3. +
    3. Fill Day 2 rows in Challenge Tracking Log with evidence links. + Why this matters: Day 2 validates local workflow, review quality, and capstone readiness.
      4. +
    +
    • +

  • +All bonus challenges A to E tracked with status and evidence or deferral reason. + Verification steps:

    +
      +
    1. Execute Phase 6 Bonus path walkthrough.
      2. +
    2. Mark each bonus row Pass, Fail, or Deferred with rationale.
      3. +
    3. Attach evidence link or deferral reason for all five bonus items. + Why this matters: optional learner paths still require QA accountability.
      4. +
    +
    • +

  • +Challenge reliability and failure-mode coverage completed for all challenge families. + Verification steps:

    +
      +
    1. Execute the full Challenge Reliability and Failure-Mode Coverage section.
      2. +
    2. Validate at least one happy path and one variation path per challenge family.
      3. +
    3. Confirm recovery behavior is tested, not assumed. + Why this matters: production reliability is defined by recovery from failure paths, not only happy-path success.
      4. +
    +
    • +

  • +Student-visible expected state map was verified at each stage. + Verification steps:

    +
      +
    1. Execute the Student-visible expected state map cross-check.
      2. +
    2. Compare observed state to each stage row in the table.
      3. +
    3. Log any mismatch as a defect before sign-off. + Why this matters: this verifies the learner experience directly, not just backend workflow success.
      4. +
    +
    • +

  • +Recovery/reset playbook validated with at least one Level 2 restore test. + Verification steps:

    +
      +
    1. Execute Student recovery and reset playbook Level 2 flow.
      2. +
    2. Confirm restored files are proposed through branch and PR evidence.
      3. +
    3. Record restore test repository, branch, and PR links. + Why this matters: facilitators need a proven restoration path during live delivery incidents.
      4. +
    +
    • +

  • +Aria, progression, and autograder workflows validated with evidence. + Verification steps:

    +
      +
    1. Execute checks in the Workflow and Automation Validation Matrix for pr-validation-bot.yml, student-progression.yml, and all autograder workflows.
      2. +
    2. Capture one pass and one actionable-fail evidence sample where applicable.
      3. +
    3. Confirm feedback is clear enough for student self-recovery. + Why this matters: these workflows are the core automated coaching and grading systems.
      4. +
    +
    • +

  • +Open defects documented with owner and due date. + Verification steps:

    +
      +
    1. Review QA notes for all unresolved findings.
      2. +
    2. Ensure each defect has severity, owner, and due date.
      3. +
    3. Confirm blocker defects are explicitly marked for release decision. + Why this matters: unresolved defects without ownership are operational risk hidden as "known issues."
      4. +
    +
    • +

  • +Release owner signs go or no-go decision. + Verification steps:

    +
      +
    1. Confirm all required checklist items above are complete or have explicit risk acceptance.
      2. +
    2. Populate Completion Output Template with final links and outcomes.
      3. +
    3. Capture release owner decision (Go or No-Go) with approver name and date. + Why this matters: formal accountability prevents ambiguous launch decisions.
      4. +
    +
    • +
+

Troubleshooting and Rollback Quick Actions

+

Use this section when a blocker appears during QA.

+
    +

  1. Registration invite automation issue:

    +
      +
    • Step 1: Confirm CLASSROOM_ORG_ADMIN_TOKEN and CLASSROOM_ORG values are present and correctly scoped.
      • +
    • Step 2: If automation is still failing, disable org invite automation by clearing CLASSROOM_ORG.
      • +
    • Step 3: Continue registration flow with manual classroom invite process.
      • +
    • Verify: registration workflow still posts welcome response and assignment links as configured.
      • +
    +
    2. +

  2. Seeding failure:

    +
      +
    • Step 1: Re-run seeding script with explicit repository slug and assignee.
      • +
    • Step 2: Confirm target repo exists and Actions are enabled.
      • +
    • Step 3: Confirm template workflow inventory includes seeding dependencies.
      • +
    • Verify: expected challenge issue appears and is assigned correctly.
      • +
    +
    3. +

  3. Progression not creating next issue:

    +
      +
    • Step 1: Confirm current challenge issue was closed, not left open with comment only.
      • +
    • Step 2: Confirm student-progression.yml exists in target repository and has successful run history.
      • +
    • Step 3: Re-dispatch progression workflow if needed.
      • +
    • Verify: next challenge issue appears with correct numbering.
      • +
    +
    4. +

  4. Autograder mismatch:

    +
      +
    • Step 1: Re-check exact autograder command/settings definitions in admin/classroom/autograding-setup.md.
      • +
    • Step 2: Trigger known-fail and known-pass scenarios for the affected autograder.
      • +
    • Step 3: Compare observed output with expected rubric behavior.
      • +
    • Verify: fail messages are actionable and pass state is reachable with correct student behavior.
      • +
    +
    5. +
+

Escalation rule:

+
    +
  1. If blocker persists after one remediation cycle, log defect with owner and ETA.
    2. +
  2. Continue with unaffected phases only when blocker impact is clearly isolated.
    3. +
+

Why this matters:

+
    +
  • Fast, repeatable recovery protects cohort timelines and prevents hidden release risk.
    • +
+

Completion Output Template (Copy into QA Issue)

+

Before publishing the completion output:

+
    +
  1. Confirm all required Phase 8 checklist items are complete or explicitly risk-accepted.
    2. +
  2. Ensure every section below includes links, not placeholders.
    3. +
  3. Attach defect list with owner and due date for any unresolved findings.
    4. +
  4. Capture final approver and decision timestamp.
    5. +
+

Why this matters:

+
    +
  • This output is the release audit record and must be independently reviewable.
    • +
+
Runbook Version: admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md
+Date:
+QA Owner:
+Facilitator Account:
+Test Student Account:
+
+Registration QA:
+- Happy path:
+- Duplicate path:
+- Waitlist path:
+- CSV export:
+- Roster sync:
+
+Classroom QA:
+- Day 1 assignment URL:
+- Day 2 assignment URL:
+- Day 1 repo URL:
+- Day 2 repo URL:
+
+Challenge QA:
+- Chapter walkthrough complete (00-21 + Appendix A-Z):
+- Supporting non-chapter content walkthrough complete:
+- Day 1 complete (1-9):
+- Day 2 complete (10-16):
+- Challenge reliability/failure-mode coverage complete:
+- Student-visible expected state map verified:
+- Recovery Level 2 restore test completed:
+- Bonus A status:
+- Bonus B status:
+- Bonus C status:
+- Bonus D status:
+- Bonus E status:
+
+Automation QA:
+- Registration workflow:
+- Registration form/label setup:
+- Aria:
+- Content validation:
+- Progression:
+- Skills progression:
+- Autograders:
+- Seeding scripts:
+
+Open Defects:
+- [ID] Severity | Owner | ETA
+
+Release Decision:
+- Go / No-Go
+- Approver:
+
+

What This Runbook Replaces

+

This runbook is the operator-facing execution path that unifies registration, deployment, and end-to-end challenge QA.

+

It does not replace source documents. It sequences them into one practical checklist so a single facilitator can execute and validate the full system without context switching across multiple folders.

+ + + \ No newline at end of file diff --git a/admin/qa-bundle/admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md b/admin/qa-bundle/admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md new file mode 100644 index 0000000..4eb253c --- /dev/null +++ b/admin/qa-bundle/admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md @@ -0,0 +1,1339 @@ +# 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: + +1. Registration intake and validation. +2. GitHub Classroom deployment and assignment setup. +3. Test account acceptance and repository seeding. +4. Full student walkthrough of every challenge path. +5. 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 + +The following table lists the source files this runbook consolidates. + +| Area | Source file | +|---|---| +| Registration entry page | [REGISTER.md](../REGISTER.md) | +| Registration automation admin | [REGISTRATION-ADMIN.md](REGISTRATION-ADMIN.md) | +| Registration automation quickstart | [REGISTRATION-QUICKSTART.md](REGISTRATION-QUICKSTART.md) | +| Registration workflow logic | [.github/workflows/registration.yml](../.github/workflows/registration.yml) | +| Classroom deployment | [classroom/README.md](../classroom/README.md) | +| Assignment copy and autograding setup | [admin/classroom/README.md](classroom/README.md) | +| Human challenge walkthrough | [classroom/HUMAN_TEST_MATRIX.md](../classroom/HUMAN_TEST_MATRIX.md) | +| Challenge definitions | [docs/CHALLENGES.md](../docs/CHALLENGES.md) | +| Student starting path | [docs/get-going.md](../docs/get-going.md) | +| Grading criteria | [classroom/grading-guide.md](../classroom/grading-guide.md) | +| Release gate baseline | [GO-LIVE-QA-GUIDE.md](../GO-LIVE-QA-GUIDE.md) | + +## Required Accounts, Access, and Tools + +Complete this section before Phase 1. + +- Facilitator admin account with Owner or Admin access to the workshop organization and classroom organization. +- Dedicated non-admin test student account for acceptance and full challenge walkthrough. +- Access to [classroom.github.com](https://classroom.github.com). +- Access to repository settings for secrets and variables. +- Local clone of this repository with PowerShell available. +- GitHub CLI (`gh`) installed and authenticated for optional verification commands. + +### Critical Precondition Gates (No-Go if any fail) + +Complete all items below before any cohort launch actions. + +- [ ] Facilitator account can access both organizations involved in operations: + - [ ] `Community-Access` + - [ ] `Community-Access-Classroom` (or your classroom org) +- [ ] Facilitator account has verified email and can create/edit Classroom assignments. +- [ ] Dedicated non-admin test student account exists and can accept invites. +- [ ] `gh auth status` succeeds for facilitator account 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: + - [ ] Secret: `CLASSROOM_ORG_ADMIN_TOKEN` + - [ ] Variables: `CLASSROOM_ORG`, `CLASSROOM_DAY1_ASSIGNMENT_URL`, `CLASSROOM_DAY2_ASSIGNMENT_URL` +- [ ] Registration entry configuration exists and is valid: + - [ ] Issue form template `workshop-registration.yml` exists + - [ ] Required labels exist: `registration`, `duplicate`, `waitlist` +- [ ] Facilitator can open `classroom.github.com`, view target classroom org, and create assignments. + +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 + +1. Sign in as the facilitator account on github.com. +2. Open your profile menu, then Your organizations. +3. Confirm both organizations are visible and accessible: + - `Community-Access` + - `Community-Access-Classroom` (or your classroom org) +4. Open both org pages and confirm you can view repositories and settings areas you are expected to manage. +5. Optional CLI verification from repository root: + +```powershell +gh auth status -h github.com +gh repo view Community-Access/git-going-with-github +gh repo view Community-Access/learning-room-template +``` + +Why this matters: + +- All downstream setup fails if the facilitator identity is not correctly scoped. + +#### B. Configure registration automation key and variables + +Repository target: `Community-Access/git-going-with-github` + +1. Open repository Settings. +2. Open Secrets and variables, then Actions. +3. Open the Secrets tab and create or update secret: + - `CLASSROOM_ORG_ADMIN_TOKEN` +4. Open the Variables tab and create or update variables: + - `CLASSROOM_ORG` + - `CLASSROOM_DAY1_ASSIGNMENT_URL` + - `CLASSROOM_DAY2_ASSIGNMENT_URL` +5. Re-open each entry and confirm values have no leading or trailing spaces. +6. Run one registration test and confirm welcome comment contains assignment links when variables are set. + +Why this matters: + +- These values drive invite and assignment-link injection in registration responses. + +#### C. Configure template repository Actions permissions + +Repository target: `Community-Access/learning-room-template` + +1. Open repository Settings. +2. Open Actions, then General. +3. In Actions permissions, ensure Actions are enabled for the repository. +4. In Workflow permissions, set `GITHUB_TOKEN` to Read and write permissions. +5. Enable Allow GitHub Actions to create and approve pull requests. +6. Save changes. + +Why this matters: + +- Template automation and bot workflows require write-capable workflow token behavior. + +#### D. Confirm the repository is a template and hosted in Community-Access + +1. Open `Community-Access/learning-room-template`. +2. Open Settings, then General. +3. Confirm the repository is marked as a template repository. +4. Confirm default branch is `main`. + +Why this matters: + +- Classroom assignment creation depends on the repository being available as a template. + +#### E. Confirm the latest learning-room content is deployed to Community-Access template + +1. From repository root, run: + +```powershell +scripts/classroom/Prepare-LearningRoomTemplate.ps1 -Owner Community-Access -TemplateRepo learning-room-template +``` + +2. If the script reports changes, open and merge the generated sync pull request in `Community-Access/learning-room-template`. +3. If the script reports no changes, capture that output as evidence. +4. Verify merged PR (or no-change output) in QA notes. + +Why this matters: + +- This is the control point that proves Community-Access template content is current. + +#### F. Prove freshness from a new template-generated repository + +1. Run: + +```powershell +scripts/classroom/Test-LearningRoomTemplate.ps1 -Owner Community-Access -TemplateRepo learning-room-template -KeepSmokeRepo +``` + +2. Open the retained smoke repository. +3. Compare at least three files changed in the most recent template sync PR: + - one workflow file + - one issue template file + - one docs or script file +4. Confirm file content in smoke repo matches merged sync PR content. +5. Record comparison links and outcome in QA notes. + +Why this matters: + +- This proves newly created student repositories inherit the latest template state, not stale content. + +## Test Artifacts You Will Produce + +Collect the following evidence while running QA. + +- Screenshots of registration confirmation and waitlist behavior. +- Screenshot of Day 1 and Day 2 assignment configuration pages. +- Screenshot of Day 1 and Day 2 autograding test lists with correct counts. +- Link to Learning Room template sync PR (or explicit no-change output) before cohort launch. +- Evidence of template smoke validation from a repo created from `Community-Access/learning-room-template`. +- Links to test student Day 1 and Day 2 repositories. +- Screenshot or link proving Challenge 1 and Challenge 10 seeding succeeded. +- Links to PRs used to validate Aria and autograders. +- Evidence that progression creates the next issue after close. +- Completed chapter-by-chapter walkthrough tracker for all required docs files. +- Completed challenge tracker for Challenges 1 to 16 and Bonus A to E. +- Final sign-off checklist with pass/fail and owner notes. + +### Artifact Capture Procedure (Required) + +Use this procedure for every artifact in this section: + +1. Capture evidence immediately after the validation action completes. +2. Name the evidence with timestamp, phase, and short description. +3. Store URL-based evidence whenever possible; use screenshots when URL evidence is not available. +4. Add one-line context in QA notes describing what the evidence proves. +5. If evidence cannot be captured, log a defect and do not mark the related gate complete. + +Why this matters: + +- Sign-off quality depends on auditable evidence, not memory or verbal confirmation. + +## Runbook Execution Standard (Applies to Every Phase) + +Follow this standard across the entire runbook. + +1. Read the phase goal and pass criteria before performing actions. +2. Execute steps in order unless the runbook explicitly permits parallel execution. +3. After each major step, capture evidence and log result as Pass, Fail, or Blocked. +4. When a step fails, stop, execute troubleshooting guidance, and document outcome before continuing. +5. Do not mark a phase complete until all pass criteria are satisfied or formally risk-accepted. + +Why this matters: + +- Consistent execution prevents partial validation and improves handoff reliability between operators. + +## QA Validation Contract (What, Where, When, How, Expected Experience) + +Use this section as the operational standard for every phase. + +| What to validate | Where to validate | When expected | How to validate | Expected experience | +|---|---|---|---|---| +| Registration issue form opens with prefilled title | Public registration page and GitHub issue form | Immediately after selecting registration link | Open the registration form link from [REGISTER.md](../REGISTER.md) | Form opens with `[REGISTER]` prefilled and correct template fields | +| Registration labels and form template are present | Repository issues/labels and `.github/ISSUE_TEMPLATE` | Before first registration test | Verify labels and `workshop-registration.yml` exist | Registration workflow can label and process issues without setup errors | +| Registration confirmation behavior | Registration issue thread and Actions run for `registration.yml` | Within 1-3 minutes of issue submission | Submit test registration and inspect comment and labels | Welcome comment appears, `registration` label applied, no manual intervention required | +| Classroom invite link injection in confirmation | Same registration issue welcome comment | Same workflow run as registration confirmation | Confirm assignment URL variables are configured and inspect comment body | Day 1 and Day 2 links appear exactly once and are clickable | +| Duplicate registration handling | Duplicate registration issue | Within 1-3 minutes of duplicate submission | Submit second registration from same account | Issue auto-closed, `duplicate` label applied, link to original issue included | +| Waitlist behavior | Registration issue and labels | Within 1-3 minutes when capacity threshold is met | Validate in safe staging path or controlled test | Waitlist message appears and `waitlist` label applied | +| Classroom assignment creation | GitHub Classroom UI | During deployment phase before student testing | Configure Day 1 and Day 2 using source docs | Assignment fields match source of truth and are published | +| Student repo creation after acceptance | Classroom dashboard and student account repositories | 30-60 seconds after invite acceptance | Accept Day 1 and Day 2 invite URLs with test student account | Separate private repos are created and visible to facilitator and test student | +| Challenge seeding | Test student repository Issues tab | Within 30-90 seconds after seeding script run | Run seeding scripts and refresh Issues | Correct starting challenge appears and is assigned correctly | +| PR validation feedback (Aria) | Test student pull request comments and Actions | Within approximately 60 seconds after PR open/update | Open PR and push another commit | Single bot comment appears and updates rather than duplicating | +| Content validation feedback | Test student PR checks/comments and Actions | Within approximately 60 seconds after PR open/update | Include link/markdown/accessibility issues and inspect output | Required fixes and suggestions are clear and tied to changed files | +| Progression behavior | Test student Issues tab and Actions for student progression | After each challenge issue closure | Close challenge issue sequentially | Next challenge opens automatically with correct number/title | +| Skills progression behavior | PR merged event and resulting comment/workflow output | After PR merge | Merge test PR and inspect workflow output | Achievement/progress feedback posts without workflow failure | +| Autograder behavior | Classroom grading panel, PR checks, and Actions logs | On relevant challenge events | Trigger known pass and known fail for each autograded challenge | Failing scenarios are understandable and pass after correct fix | +| Chapter content consistency | Markdown files under [docs](../docs/README.md) | During curriculum review phase before sign-off | Execute full chapter and appendix checklist | All required docs reviewed and discrepancies logged | +| Challenge coverage completeness | Challenge tracking table in this runbook | During student journey execution | Fill all rows for 1-16 and A-E | No challenge row is left blank or untracked | + +## Reading Order for Operators + +Read these files in this exact order before executing the runbook. + +1. [REGISTRATION-QUICKSTART.md](REGISTRATION-QUICKSTART.md) +2. [REGISTRATION-ADMIN.md](REGISTRATION-ADMIN.md) +3. [classroom/README.md](../classroom/README.md) +4. [admin/classroom/autograding-setup.md](classroom/autograding-setup.md) +5. [classroom/HUMAN_TEST_MATRIX.md](../classroom/HUMAN_TEST_MATRIX.md) +6. [docs/CHALLENGES.md](../docs/CHALLENGES.md) + +Reading completion rule: + +1. Do not begin Phase 0 until all files above are opened and skimmed for current cohort context. +2. Log "reading complete" with timestamp in QA notes. + +Why this matters: + +- Most setup errors come from skipping source-of-truth docs before execution. + +## Pre-Flight Local Validation (Non-Podcast) + +Run these from repository root before live environment QA. + +```powershell +npm run test:automation +npm run build:html +git diff --check +``` + +Pass criteria: + +- Automation tests pass. +- HTML build completes. +- No unresolved conflict markers or whitespace check failures. + +### Local unit-test evidence requirements + +Record and publish local test evidence under [admin/qa-readiness](qa-readiness/README.md). + +Minimum evidence: + +- Test command used. +- Total tests, pass count, fail count. +- Any failing tests and remediation actions. +- Residual risk statement for hosted GitHub behavior not proven by local tests. + +Recommended report format: + +- [admin/qa-readiness/UNIT-TEST-RESULTS-2026-05-08.md](qa-readiness/UNIT-TEST-RESULTS-2026-05-08.md) + +No-go rule: + +- If local readiness tests fail, do not proceed to template deployment or classroom assignment setup. + +Execution procedure: + +1. Run commands in listed order from repository root. +2. Capture terminal output snippets for each command. +3. If any command fails, record failure cause and remediation attempt. +4. Re-run failed command after remediation and capture final outcome. + +Why this matters: + +- Pre-flight catches local defects before they become live Classroom failures. + +## Phase 0 - Registration System Deployment Gate (Admin Side) + +This phase is mandatory. Do not run registration QA tests until deployment/configuration is complete. + +### Step 0.1 Deploy registration issue form and workflow prerequisites + +Goal: ensure the registration intake system is deployed and configured for this course cohort. + +1. Confirm registration issue form template exists and is current: + - `.github/ISSUE_TEMPLATE/workshop-registration.yml` +2. Confirm registration workflow exists and is enabled: + - `.github/workflows/registration.yml` +3. Confirm required labels exist in repository: + - `registration` + - `duplicate` + - `waitlist` +4. Confirm repository Actions are enabled for this repository. + +Pass criteria: + +- Issue form template is present and selectable from "New issue". +- Registration workflow is enabled and visible in Actions. +- Required labels exist and are usable. + +### Step 0.2 Deploy optional registration-to-classroom automation settings + +Goal: enable automatic org invite and assignment-link injection in registration confirmation comments. + +1. In repository settings, configure secret: + - `CLASSROOM_ORG_ADMIN_TOKEN` +2. In repository settings, configure variables: + - `CLASSROOM_ORG` + - `CLASSROOM_DAY1_ASSIGNMENT_URL` + - `CLASSROOM_DAY2_ASSIGNMENT_URL` +3. Re-open each value and verify no leading or trailing spaces. + +Pass criteria: + +- Secret and variables are present with correct values. +- Configuration aligns with [REGISTRATION-ADMIN.md](REGISTRATION-ADMIN.md). + +### Step 0.3 Registration deployment smoke check + +Goal: validate deployed registration system can execute at least one full workflow run. + +1. Submit one test registration issue from a non-admin test account. +2. Confirm `Registration - Welcome & CSV Export` workflow completes. +3. Confirm welcome comment posts and `registration` label is applied. +4. If classroom automation is configured, confirm org invite status and assignment links appear. + +Pass criteria: + +- Registration workflow executes successfully end to end. +- Output comment/labels match deployed configuration. + +## Phase 1 - Registration System QA (Admin Side) + +### Step 1. Verify public registration entry path + +1. Open [REGISTER.md](../REGISTER.md) and confirm the registration link points to the issue form template with `workshop-registration.yml`. +2. Open the rendered registration page and activate the registration form link. +3. Confirm the issue form opens with `[REGISTER]` in the title. +4. Confirm the page communicates that registration issues are public. + +Pass criteria: +- Registration link opens correctly. +- Registration issue title is prefilled with `[REGISTER]`. +- Public visibility warning is present. + +### Step 2. Configure registration automation for classroom handoff + +Use [REGISTRATION-QUICKSTART.md](REGISTRATION-QUICKSTART.md) for fast entry and [REGISTRATION-ADMIN.md](REGISTRATION-ADMIN.md) for full details. + +1. Create or verify an admin token that can manage organization invitations. +2. In repository settings, add secret `CLASSROOM_ORG_ADMIN_TOKEN`. +3. In repository settings, set variables: + - `CLASSROOM_ORG` + - `CLASSROOM_DAY1_ASSIGNMENT_URL` + - `CLASSROOM_DAY2_ASSIGNMENT_URL` +4. Save and re-open each setting to confirm there are no leading or trailing spaces. + +Pass criteria: +- Secret exists and is scoped correctly. +- All 3 variables exist and values are correct. + +### Step 3. Execute registration happy-path test + +Use the non-admin test student account. + +1. Submit the registration issue form once. +2. Wait for `Registration - Welcome & CSV Export` workflow to complete. +3. Confirm the issue receives a welcome comment. +4. Confirm the welcome comment includes: + - Zoom registration information. + - Day 1 and Day 2 assignment links (if variables are set). + - Organization invitation status when classroom org automation is active. +5. Confirm `registration` label is applied. + +Pass criteria: +- Workflow succeeds. +- Comment content is complete and accurate. +- `registration` label exists on the issue. + +### Step 4. Execute duplicate and waitlist tests + +1. Submit a second registration issue from the same test account. +2. Confirm workflow marks the issue duplicate and closes it with guidance to the original issue. +3. For waitlist behavior, use a controlled test strategy: + - Preferred: run in a staging copy where capacity can be reached safely. + - Alternative: dry-run logic review from [.github/workflows/registration.yml](../.github/workflows/registration.yml) and verify conditions with maintainers. +4. Confirm waitlist message and `waitlist` label behavior in the chosen test environment. + +Pass criteria: +- Duplicate submission closes with duplicate guidance. +- Waitlist path and label behavior are validated. + +### Step 5. Verify CSV export and roster sync outputs + +1. Open the workflow run artifacts and download `registration-data`. +2. Confirm CSV includes expected columns and test user row. +3. Verify `.github/data/student-roster.json` is updated by workflow with non-PII operational fields. +4. Optionally trigger manual rebuild: + +```powershell +gh workflow run registration.yml -R community-access/git-going-with-github +``` + +Pass criteria: +- CSV artifact is present and parseable. +- Roster sync commit appears only when data changed. + +## Phase 2 - Learning Room Template Deployment Gate (Admin Side) + +This phase is mandatory. Do not create Classroom assignments until this gate is complete. + +### Step 6. Sync local Learning Room source into GitHub template repository + +Goal: ensure `Community-Access/learning-room-template` reflects the latest source from `learning-room/`. + +Run from repository root: + +```powershell +scripts/classroom/Prepare-LearningRoomTemplate.ps1 -Owner Community-Access -TemplateRepo learning-room-template +``` + +What to expect: + +1. Script verifies GitHub CLI auth. +2. Script ensures template repository settings (template mode and Actions permissions where allowed). +3. Script creates a sync branch and PR if changes exist. +4. If no changes exist, script reports no template changes to commit. + +Where to verify: + +- `Community-Access/learning-room-template` pull requests list. +- Template repository Actions/settings page. + +Pass criteria: + +- Template sync PR exists and is merged to `main`, or script reports no changes required. +- Template repository remains configured as a template repository. +- Template repository default branch is `main` and visible in repository settings. + +### Step 7. Validate published template with smoke repository + +Goal: prove that new repos created from the template include required workflows/templates and can trigger challenge progression. + +Run from repository root: + +```powershell +scripts/classroom/Test-LearningRoomTemplate.ps1 -Owner Community-Access -TemplateRepo learning-room-template +``` + +What to expect: + +1. Script creates a temporary private smoke repo from the template. +2. Script checks key files exist (student progression workflow, challenge template, progression script). +3. Script triggers Challenge 1 workflow dispatch. +4. Script deletes smoke repo unless `-KeepSmokeRepo` is specified. + +Where to verify: + +- Smoke repo creation/deletion in GitHub repos list. +- Workflow run history and issue creation in smoke repo when retained. + +Pass criteria: + +- Smoke repo creation succeeds from template. +- Required files exist in smoke repo. +- Challenge 1 workflow dispatch succeeds. +- Smoke repo validates workflow inventory: + - `pr-validation-bot.yml` + - `content-validation.yml` + - `student-progression.yml` + - `skills-progression.yml` + - `autograder-conflicts.yml` + - `autograder-local-commit.yml` + - `autograder-template.yml` + - `autograder-capstone.yml` + +### Step 8. Prove template freshness (latest release content is live) + +Goal: confirm that newly created repositories are generated from the latest deployed template content, not stale template state. + +1. Keep the smoke repository (`-KeepSmokeRepo`) or create another temporary smoke repo from template. +2. Open the merged template sync PR from Step 6. +3. Select at least 3 files changed in that PR, including at least: + - one workflow file, + - one issue template file, + - one docs or script file. +4. Verify those exact file changes are present in the smoke repository. +5. Record evidence links in your QA notes. + +Pass criteria: + +- Evidence shows smoke repo content matches the latest merged template sync changes. +- No stale-file mismatch is found. + +### Step 9. Optional comprehensive harness check + +For deeper verification, run: + +```powershell +scripts/classroom/Invoke-LearningRoomEndToEndTest.ps1 -SelfTest +``` + +Use full end-to-end mode when preparing major cohort launches or after significant automation updates. + +## Phase 3 - Classroom Deployment QA (Admin Side) + +### Step 10. Create classroom and import roster + +Use [classroom/README.md](../classroom/README.md) Steps 1 and 2. + +1. Create a new classroom in `Community-Access`. +2. Name it using `Git Going - [Cohort Name] - [Month Year]`. +3. Import roster using [classroom/roster-template.csv](../classroom/roster-template.csv). +4. Confirm test student appears in roster. + +Pass criteria: +- Classroom exists and is accessible to facilitators. +- Roster import succeeds with expected usernames. + +### Step 11. Create Day 1 assignment exactly + +Use [classroom/assignment-day1-you-belong-here.md](../classroom/assignment-day1-you-belong-here.md) and [admin/classroom/day1-assignment-copy-paste.md](classroom/day1-assignment-copy-paste.md). + +1. Create assignment with title `You Belong Here`. +2. Set type `Individual`. +3. Set visibility `Private`. +4. Select template `Community-Access/learning-room-template`. +5. Set `Grant students admin access` to `No`. +6. Set `Enable feedback pull requests` to `Yes`. +7. Paste Day 1 assignment description content. +8. Add Day 1 autograding entries from [admin/classroom/autograding-setup.md](classroom/autograding-setup.md). +9. Confirm Day 1 has 4 tests and total 50 points. +10. Save assignment and copy invite link. + +Pass criteria: +- Day 1 settings match source files exactly. +- Test count and points are correct. +- Feedback pull request is enabled and visible in assignment configuration. + +### Step 12. Create Day 2 assignment exactly + +Use [classroom/assignment-day2-you-can-build-this.md](../classroom/assignment-day2-you-can-build-this.md) and [admin/classroom/day2-assignment-copy-paste.md](classroom/day2-assignment-copy-paste.md). + +1. Create assignment with title `You Can Build This`. +2. Apply same base settings as Day 1 (individual, private, no admin access, feedback PR enabled). +3. Paste Day 2 assignment description content. +4. Add Day 2 autograding entries from [admin/classroom/autograding-setup.md](classroom/autograding-setup.md). +5. Confirm Day 2 has 6 tests and total 75 points. +6. Save assignment and copy invite link. + +Pass criteria: +- Day 2 settings match source files exactly. +- Test count and points are correct. +- Feedback pull request is enabled and visible in assignment configuration. + +### Step 13. Connect assignment URLs back to registration automation + +1. Add or update repository variables: + - `CLASSROOM_DAY1_ASSIGNMENT_URL` + - `CLASSROOM_DAY2_ASSIGNMENT_URL` +2. Re-run one registration test issue (new test account or controlled case). +3. Confirm both links appear in welcome comment. + +Pass criteria: +- Registration confirmation comment now includes both assignment URLs. + +## Phase 4 - Test Student Acceptance and Seeding (Bridge from Admin to Student) + +### Step 14. Test student accepts Day 1 and Day 2 invites + +Use the test student account. + +1. Open Day 1 invite URL. +2. Accept assignment and wait for repo creation. +3. Record Day 1 test repo URL. +4. Open Day 2 invite URL. +5. Accept assignment and wait for repo creation. +6. Record Day 2 test repo URL. + +Pass criteria: +- Two private repos are created and visible in classroom dashboard. + +### Step 15. Seed initial challenges and peer simulation + +Run commands from repository root. + +```powershell +scripts/classroom/Seed-LearningRoomChallenge.ps1 -Repository Community-Access-Classroom/learning-room-test-student-day1 -Challenge 1 -Assignee test-student +scripts/classroom/Seed-PeerSimulation.ps1 -Repository Community-Access-Classroom/learning-room-test-student-day1 -StudentUsername test-student +scripts/classroom/Seed-LearningRoomChallenge.ps1 -Repository Community-Access-Classroom/learning-room-test-student-day2 -Challenge 10 -Assignee test-student +scripts/classroom/Seed-PeerSimulation.ps1 -Repository Community-Access-Classroom/learning-room-test-student-day2 -StudentUsername test-student +``` + +If you use different repository names, replace values accordingly. + +Pass criteria: +- Challenge 1 appears in Day 1 repo. +- Challenge 10 appears in Day 2 repo. +- Peer simulation issues and PR exist in both repos. + +## Phase 5 - Curriculum Content QA (Walk every required chapter and appendix) + +This phase is required. Do not skip this phase even if challenge automation is passing. + +### Step 16. Execute full chapter and appendix walkthrough + +For each file listed below, open it and verify: + +1. Instructions are accurate for the current Classroom model. +2. Links resolve or are intentionally marked as practice targets. +3. Accessibility language is actionable and not visual-only. +4. Challenge references align with [docs/CHALLENGES.md](../docs/CHALLENGES.md). + +Use this per-file verification routine before checking each box: + +1. Open the file and read it once top to bottom without editing. +2. Re-read while validating the 4 checks above and capture any defects in your QA notes. +3. If no defect is found, mark the checkbox complete immediately. +4. If a defect is found, leave checkbox open until defect is logged with owner and due date. + +Why this matters: + +- This prevents "skim and check" behavior that misses broken learner paths. +- It ensures every completed checkbox represents a defensible QA review, not just a visual pass. + +Track completion using this checklist. + +Core learner docs: + +- [ ] [docs/get-going.md](../docs/get-going.md) +- [ ] [docs/course-guide.md](../docs/course-guide.md) +- [ ] [docs/student-onboarding.md](../docs/student-onboarding.md) +- [ ] [docs/CHALLENGES.md](../docs/CHALLENGES.md) + +Core chapters: + +- [ ] [docs/00-pre-workshop-setup.md](../docs/00-pre-workshop-setup.md) +- [ ] [docs/01-choose-your-tools.md](../docs/01-choose-your-tools.md) +- [ ] [docs/02-understanding-github.md](../docs/02-understanding-github.md) +- [ ] [docs/03-navigating-repositories.md](../docs/03-navigating-repositories.md) +- [ ] [docs/04-the-learning-room.md](../docs/04-the-learning-room.md) +- [ ] [docs/05-working-with-issues.md](../docs/05-working-with-issues.md) +- [ ] [docs/06-working-with-pull-requests.md](../docs/06-working-with-pull-requests.md) +- [ ] [docs/07-merge-conflicts.md](../docs/07-merge-conflicts.md) +- [ ] [docs/08-open-source-culture.md](../docs/08-open-source-culture.md) +- [ ] [docs/09-labels-milestones-projects.md](../docs/09-labels-milestones-projects.md) +- [ ] [docs/10-notifications-and-day-1-close.md](../docs/10-notifications-and-day-1-close.md) +- [ ] [docs/11-vscode-interface.md](../docs/11-vscode-interface.md) +- [ ] [docs/12-vscode-accessibility.md](../docs/12-vscode-accessibility.md) +- [ ] [docs/13-how-git-works.md](../docs/13-how-git-works.md) +- [ ] [docs/14-git-in-practice.md](../docs/14-git-in-practice.md) +- [ ] [docs/15-code-review.md](../docs/15-code-review.md) +- [ ] [docs/16-github-copilot.md](../docs/16-github-copilot.md) +- [ ] [docs/17-issue-templates.md](../docs/17-issue-templates.md) +- [ ] [docs/18-fork-and-contribute.md](../docs/18-fork-and-contribute.md) +- [ ] [docs/19-accessibility-agents.md](../docs/19-accessibility-agents.md) +- [ ] [docs/20-build-your-agent.md](../docs/20-build-your-agent.md) +- [ ] [docs/21-next-steps.md](../docs/21-next-steps.md) + +Appendices: + +- [ ] [docs/appendix-a-glossary.md](../docs/appendix-a-glossary.md) +- [ ] [docs/appendix-b-screen-reader-cheatsheet.md](../docs/appendix-b-screen-reader-cheatsheet.md) +- [ ] [docs/appendix-c-markdown-reference.md](../docs/appendix-c-markdown-reference.md) +- [ ] [docs/appendix-d-git-authentication.md](../docs/appendix-d-git-authentication.md) +- [ ] [docs/appendix-e-advanced-git.md](../docs/appendix-e-advanced-git.md) +- [ ] [docs/appendix-f-git-security.md](../docs/appendix-f-git-security.md) +- [ ] [docs/appendix-g-vscode-reference.md](../docs/appendix-g-vscode-reference.md) +- [ ] [docs/appendix-h-github-desktop.md](../docs/appendix-h-github-desktop.md) +- [ ] [docs/appendix-i-github-cli.md](../docs/appendix-i-github-cli.md) +- [ ] [docs/appendix-j-cloud-editors.md](../docs/appendix-j-cloud-editors.md) +- [ ] [docs/appendix-k-copilot-reference.md](../docs/appendix-k-copilot-reference.md) +- [ ] [docs/appendix-l-agents-reference.md](../docs/appendix-l-agents-reference.md) +- [ ] [docs/appendix-m-accessibility-standards.md](../docs/appendix-m-accessibility-standards.md) +- [ ] [docs/appendix-n-advanced-search.md](../docs/appendix-n-advanced-search.md) +- [ ] [docs/appendix-o-branch-protection.md](../docs/appendix-o-branch-protection.md) +- [ ] [docs/appendix-p-security-features.md](../docs/appendix-p-security-features.md) +- [ ] [docs/appendix-q-actions-workflows.md](../docs/appendix-q-actions-workflows.md) +- [ ] [docs/appendix-r-projects-deep-dive.md](../docs/appendix-r-projects-deep-dive.md) +- [ ] [docs/appendix-s-releases-tags-insights.md](../docs/appendix-s-releases-tags-insights.md) +- [ ] [docs/appendix-t-community-and-social.md](../docs/appendix-t-community-and-social.md) +- [ ] [docs/appendix-u-discussions-and-gists.md](../docs/appendix-u-discussions-and-gists.md) +- [ ] [docs/appendix-v-github-mobile.md](../docs/appendix-v-github-mobile.md) +- [ ] [docs/appendix-w-github-pages.md](../docs/appendix-w-github-pages.md) +- [ ] [docs/appendix-x-resources.md](../docs/appendix-x-resources.md) +- [ ] [docs/appendix-y-workshop-materials.md](../docs/appendix-y-workshop-materials.md) +- [ ] [docs/appendix-z-github-skills.md](../docs/appendix-z-github-skills.md) + +Phase 4 pass criteria: +- Every listed file has been reviewed and marked complete. +- Any doc defects are logged with owner and due date. + +### Step 17. Validate supporting content outside chapters + +Review the following content surfaces because they directly affect learner and facilitator experience. + +Use this verification routine for each section below (Root docs, Classroom docs, Learning Room automation docs): + +1. Open all files in the section and compare wording for the same workflow concepts. +2. Confirm setup steps, command names, and expected outcomes match current automation behavior. +3. Confirm links between docs resolve and point to the intended destination. +4. Mark each file checkbox only after you either confirm consistency or log a specific defect. + +Why this matters: + +- Learners and facilitators often use these supporting docs first; contradictions here cause avoidable support load. +- Cross-document consistency reduces failed setup attempts during live cohorts. + +- [ ] Root docs alignment: + - [ ] [README.md](../README.md) + - [ ] [BUILD.md](../BUILD.md) + - [ ] [REGISTER.md](../REGISTER.md) + - [ ] [CONTRIBUTING.md](../CONTRIBUTING.md) + - [ ] [SECURITY.md](../SECURITY.md) + - [ ] [REPOSITORY_SECURITY.md](../REPOSITORY_SECURITY.md) +- [ ] Classroom deployment docs: + - [ ] [classroom/README.md](../classroom/README.md) + - [ ] [classroom/HUMAN_TEST_MATRIX.md](../classroom/HUMAN_TEST_MATRIX.md) + - [ ] [classroom/grading-guide.md](../classroom/grading-guide.md) +- [ ] Learning Room automation docs: + - [ ] [learning-room/.github/STUDENT_GUIDE.md](../learning-room/.github/STUDENT_GUIDE.md) + - [ ] [learning-room/.github/FACILITATOR_GUIDE.md](../learning-room/.github/FACILITATOR_GUIDE.md) + - [ ] [learning-room/.github/SETUP_AND_MAINTENANCE.md](../learning-room/.github/SETUP_AND_MAINTENANCE.md) + - [ ] [learning-room/.github/DEPLOYMENT_VALIDATION.md](../learning-room/.github/DEPLOYMENT_VALIDATION.md) + +Pass criteria: + +- Supporting docs are consistent with chapter guidance and current automation behavior. +- Any cross-document contradictions are logged as defects. + +## Phase 6 - Student Journey QA (Walk every path as a student) + +Use [classroom/HUMAN_TEST_MATRIX.md](../classroom/HUMAN_TEST_MATRIX.md) as your execution baseline and record evidence for each challenge. + +Phase execution rule: + +1. Run student journey checks in challenge order unless explicitly validating a failure-mode branch. +2. For each challenge, capture issue URL, evidence comment URL, and workflow/check outcome. +3. Update the Challenge Tracking Log row immediately after each challenge completes. +4. If progression fails, stop sequence and resolve before moving to next challenge. + +Why this matters: + +- Ordered execution is required to validate progression automation and student experience continuity. + +### Student pre-read sequence before challenge execution + +Have the tester read in this order: + +1. [docs/get-going.md](../docs/get-going.md) +2. [docs/00-pre-workshop-setup.md](../docs/00-pre-workshop-setup.md) +3. [docs/04-the-learning-room.md](../docs/04-the-learning-room.md) +4. [docs/CHALLENGES.md](../docs/CHALLENGES.md) + +### Day 1 challenge walkthrough (Challenges 1 to 9) + +For each challenge issue, perform this pattern: + +1. Open challenge issue. +2. Complete required actions. +3. Post evidence comment. +4. Close issue. +5. Confirm next challenge issue appears. + +Challenge-specific checks: + +1. Challenge 1: verify orientation tasks and next challenge creation. +2. Challenge 2: create a clear issue from `docs/welcome.md` TODO. +3. Challenge 3: comment on peer simulation issue and include mention. +4. Challenge 4: create `learn/` branch. +5. Challenge 5: commit real content change with descriptive message. +6. Challenge 6: open PR with `Closes #N` and validate Aria response. +7. Challenge 7: run conflict seeding and resolve conflict markers. +8. Challenge 8: submit culture reflection evidence. +9. Challenge 9: merge PR and confirm linked issue closes. + +Run merge conflict setup when Challenge 7 is reached: + +```powershell +scripts/classroom/Start-MergeConflictChallenge.ps1 -Repository Community-Access-Classroom/learning-room-test-student-day1 -StudentBranch learn/test-student +``` + +Day 1 pass criteria: +- Progression works across all nine challenges. +- Aria feedback appears on test PRs. +- Challenge 7 conflict-marker checks fail before fix and pass after fix. + +### Day 2 challenge walkthrough (Challenges 10 to 16) + +Use the same five-step issue pattern for each challenge. + +Challenge-specific checks: + +1. Challenge 10: clone locally, branch, edit, commit, push, and verify local commit workflow. +2. Challenge 11: open PR from Day 2 local branch and verify feedback. +3. Challenge 12: complete structured review on peer simulation PR. +4. Challenge 13: capture Copilot suggestion and student judgment. +5. Challenge 14: create custom non-challenge issue template with required fields and verify workflow. +6. Challenge 15: inspect accessibility agents and capture findings. +7. Challenge 16: fork `Community-Access/accessibility-agents`, create agent file with frontmatter, responsibilities, and guardrails, then open cross-fork PR. + +Day 2 pass criteria: +- Progression works from 10 through 16. +- Autograders for 10, 14, and 16 provide useful pass/fail feedback. +- Capstone evidence is complete and reviewable. + +### Student-visible expected state map (required cross-check) + +Use this section to confirm what students should see, where they should see it, and what artifacts should exist after each stage. + +| Stage | Where student looks | What student should see | Expected artifacts | +|---|---|---|---| +| After assignment acceptance | Repository home and Issues tab | Private Learning Room repository created from template | Starter docs (`docs/welcome.md`, `docs/keyboard-shortcuts.md`, `docs/setup-guide.md`), workflows, issue templates | +| After initial seeding | Issues tab | Correct starting challenge issue appears (`Challenge 1` or `Challenge 10`) | Assigned challenge issue with clear instructions and evidence prompt | +| During Day 1 PR flow (Ch 4-6) | Branch selector, Pull requests, Actions | Student branch exists, PR open, bot feedback appears | Branch `learn/` or equivalent, PR with `Closes #N`, Aria validation comment | +| During merge conflict (Ch 7) | PR conversation/files, Checks tab | Conflict state visible, then resolved | Conflict markers present pre-fix, removed post-fix, conflict check transitions to pass | +| During Day 2 local flow (Ch 10-11) | Local clone and remote PR | Local commit/push reflected in PR and checks | Non-default-branch commit visible in history and checks | +| During template challenge (Ch 14) | File tree and PR checks | Custom template exists and passes required-field checks | New `.github/ISSUE_TEMPLATE/*.yml` file with `name` and `description` | +| During capstone (Ch 16) | Fork repo and capstone PR | Cross-fork contribution path works with required structure | Agent file with frontmatter, responsibilities, guardrails; PR evidence | +| Bonus path | Issue templates and evidence comments | Bonus templates are available and usable | Bonus issue evidence and status recorded in tracker | + +Pass criteria: + +- Student-visible state is confirmed at each stage above. +- Any mismatch between expected and observed student experience is logged as a defect. + +### Bonus path walkthrough (A to E) + +Bonus challenges are optional for students, but QA tracking is required for every bonus challenge. + +1. Open each bonus template. +2. Confirm instructions are understandable and actionable. +3. Track completion status for each bonus challenge A to E. +4. If a bonus challenge is not fully executed, record why and what validated the path. + +Pass criteria: +- All bonus challenges A to E have explicit status and notes. +- No bonus challenge is left untracked. + +### Challenge Tracking Log (Required) + +Use this tracker while executing Phase 5. Every row must be completed. + +Row completion standard: + +1. Status must be one of Pass, Fail, or Deferred. +2. Evidence link must point to issue, PR, workflow run, or equivalent proof. +3. Notes must include remediation or deferral rationale when status is not Pass. + +Why this matters: + +- Complete row data is required for defensible release decisions and post-run audits. + +| Challenge | Title | Status (Pass/Fail/Deferred) | Evidence link | Notes | +|---|---|---|---|---| +| 1 | Find Your Way Around | | | | +| 2 | File Your First Issue | | | | +| 3 | Join the Conversation | | | | +| 4 | Branch Out | | | | +| 5 | Make Your Mark | | | | +| 6 | Open Your First Pull Request | | | | +| 7 | Survive a Merge Conflict | | | | +| 8 | The Culture Layer | | | | +| 9 | Merge Day | | | | +| 10 | Go Local | | | | +| 11 | Open a Day 2 PR | | | | +| 12 | Review Like a Pro | | | | +| 13 | AI as Your Copilot | | | | +| 14 | Template Remix | | | | +| 15 | Meet the Agents | | | | +| 16 | Build Your Agent (Capstone) | | | | +| Bonus A | Improve an Existing Agent | | | | +| Bonus B | Document Your Journey | | | | +| Bonus C | Create a Group Challenge | | | | +| Bonus D | Notification Mastery | | | | +| Bonus E | Explore Git History Visually | | | | + +### Challenge Reliability and Failure-Mode Coverage (Required) + +Do not mark the challenge system reliable until this section is completed. + +#### Reliability test personas + +Run challenge validation with at least these personas: + +- Persona A: Day 1 + Day 2 student path (full path through 1-16). +- Persona B: Day-2-only student path (starts at Challenge 10). + +#### Required variation categories + +For each applicable challenge, test and document all categories below: + +1. Happy path completion. +2. Common student error path. +3. Recovery path after feedback. +4. Automation latency/idempotency behavior (reruns, duplicate events, delayed comments). + +#### Variation matrix by challenge family + +| Challenge family | Minimum failure/variation scenarios to test | Pass criteria | +|---|---|---| +| 1-3 orientation and issue flow | Missing evidence comment, evidence posted in wrong issue, issue closed without evidence, delayed bot response on mention | Student can recover without facilitator-only intervention; instructions remain clear | +| 4-6 branch/commit/PR flow | Wrong branch, commit to main, PR missing `Closes #N`, weak PR body, duplicate PR attempts | Bot/autograder guidance is actionable and student can fix to pass | +| 7 conflict flow | Conflict markers left in file, partial resolution, wrong file resolved, reintroducing markers on next commit | Fails when unresolved, passes after true resolution, feedback explains next step | +| 8-9 culture/merge flow | Reflection too vague, merge blocked by checks, PR approved but not mergeable, issue not auto-closing | Student can complete with clear guidance and accurate merge outcome | +| 10-11 local workflow | Local auth failure, push to wrong remote/branch, no new commit, PR from wrong base | Failure mode is discoverable and recoverable with provided guidance | +| 12 review workflow | Review left as comment only, no actionable feedback, review submitted on wrong PR | Challenge guidance clarifies expectations and evidence remains evaluable | +| 13 Copilot evidence | Missing prompt/evaluation details, copied output without judgment, evidence too shallow | Student can revise evidence and meet evaluation criteria | +| 14 template workflow | Template file wrong folder/name, missing `name`, missing `description`, invalid YAML | Autograder fails correctly and passes only after true fix | +| 15 agent exploration | Superficial exploration notes, wrong repo referenced, no evidence of actual inspection | Challenge remains completable with clear evidence requirements | +| 16 capstone | Missing frontmatter, missing responsibilities/guardrails, PR to wrong repo, incomplete cross-fork setup | Autograder/checklist catches gaps and student can recover to complete | +| Bonus A-E | Student starts bonus without prerequisites, partial completion, alternate evidence format | Each bonus has documented pass/fail/deferred outcome and rationale | + +#### Cross-cutting failure modes (must be tested at least once) + +- Bot comment delay greater than expected window. +- Workflow rerun without creating duplicate progression issues. +- Student posts evidence in wrong place then corrects it. +- Autograder false-negative suspicion escalated and resolved with facilitator override process. +- Permission/access prompt encountered and resolved (student and facilitator perspectives). + +#### Reliability gate pass criteria + +- Every challenge (1-16 and Bonus A-E) has at least one documented happy path and one documented variation/failure scenario. +- Recovery steps are validated, not assumed. +- No critical failure path requires hidden facilitator knowledge outside documented guidance. + +### Student recovery and reset playbook (required) + +If a student repository is corrupted, use this escalation path. + +#### Level 1: Student self-recovery (preferred) + +1. Re-open challenge instructions and compare against required target file. +2. Use PR diff to undo accidental changes. +3. Restore missing text from template references in challenge guidance. +4. Push a corrective commit and re-run checks. + +Use when: + +- Student changed only small sections in expected challenge files. + +#### Level 2: Facilitator-assisted file restore (safe branch+PR) + +Use the recovery script to restore baseline files from `Community-Access/learning-room-template` into a student repo on a recovery branch. + +Script: + +```powershell +scripts/classroom/Restore-LearningRoomFiles.ps1 -StudentRepository Community-Access-Classroom/learning-room-studentname -Profile core-day1 -OpenPullRequest +``` + +Profiles: + +- `core-day1` restores Day 1 starter docs. +- `core-day2` restores Day 2 sample docs. +- `automation-core` restores workflow files. +- `all-core` restores all above. +- `custom` restores explicit paths provided via `-Paths`. + +Use when: + +- A challenge file, sample file, or workflow file was accidentally overwritten or deleted. + +#### Level 3: Repository re-provision fallback + +If corruption is broad and recovery branch approach is not sufficient: + +1. Export evidence links needed for grading history. +2. Remove student assignment entry in Classroom (if policy allows). +3. Re-invite student to assignment to generate a fresh repository. +4. Re-seed appropriate challenge and peer simulation artifacts. +5. Document mapping from old repo to replacement repo in facilitator notes. + +Use when: + +- Student repo is not reasonably recoverable with targeted file restores. + +#### Recovery gate pass criteria + +- At least one Level 2 recovery test is completed in QA and documented. +- Facilitators can perform targeted restore without editing files manually in GitHub UI. +- Recovery actions preserve auditability through branch/PR evidence. + +## Phase 7 - Workflow and Automation Validation Matrix + +Use this matrix as your quick final automation check. + +Matrix execution procedure: + +1. Work row by row. +2. Trigger or locate the required event for each component. +3. Verify expected behavior in the stated location. +4. Record one evidence link per row. +5. Mark row complete only when observed behavior matches expected experience. + +Why this matters: + +- The matrix is the final integration proof that automation is functioning as designed. + +| Automation component | What to verify | Where to verify | Trigger timing | Expected experience | +|---|---|---|---|---| +| `registration.yml` welcome job | New registration handling | Registration issue comment + labels + Actions run | On issue open with `[REGISTER]` | Welcome comment posted, registration label applied, no manual intervention | +| `registration.yml` duplicate logic | Duplicate handling | Duplicate issue thread + labels + closed state | On second submission by same user | Duplicate message references original and issue auto-closes | +| `registration.yml` waitlist logic | Capacity full behavior | Registration issue comment + `waitlist` label | When threshold reached in controlled test | Waitlist message and label applied | +| `registration.yml` CSV export | Registration data artifact | Actions artifacts | Every registration run or manual dispatch | `registration-data` artifact is available and current | +| `registration.yml` roster sync | Non-PII roster update | [.github/data/student-roster.json](../.github/data/student-roster.json) and workflow commit | Every registration run or manual dispatch | Roster updates only when changed and no PII stored | +| `pr-validation-bot.yml` | PR structure and guidance checks | PR comments + Actions | PR open/edit/sync/review events | Validation comment appears and updates in place | +| `content-validation.yml` | Link/markdown/accessibility checks | PR checks/comments + Actions logs | PR open/edit/sync | Clear actionable findings tied to changed files | +| `student-progression.yml` | Challenge unlock sequence | Issues tab + Actions logs | Issue close and workflow dispatch | Next challenge issue appears with correct sequence | +| `skills-progression.yml` | Skill/achievement feedback | PR comments + Actions | PR merge | Achievement/progress feedback posts without failure | +| `autograder-conflicts.yml` | Conflict marker detection for Ch07 | Actions checks + PR status | PR open/edit for conflict scenario | Fails before fix, passes after marker removal | +| `autograder-local-commit.yml` | Local commit validation for Ch10 | Actions checks + PR/status output | Push/PR for Ch10 scenario | Detects non-default-branch commit | +| `autograder-template.yml` | Issue template validation for Ch14 | Actions checks + PR/status output | Template challenge workflow trigger | Fails missing fields, passes with `name` and `description` | +| `autograder-capstone.yml` | Agent structure validation for Ch16 | Actions checks + PR/status output | Capstone PR events | Validates frontmatter, responsibilities, and guardrails | +| `Seed-LearningRoomChallenge.ps1` | Challenge seed operation | Issues tab + workflow run history | On script execution | Target challenge appears and assignment is correct | +| `Seed-PeerSimulation.ps1` | Peer simulation artifacts | Issues + PR list + branch list | On script execution | Peer simulation issues and PR appear as expected | +| `Start-MergeConflictChallenge.ps1` | Merge conflict scenario creation | Student PR conflict state + checks | On script execution during Ch07 | Conflict becomes visible and resolvable | +| `Test-LearningRoomTemplate.ps1` | Template readiness scan | Script output + remediation notes | Before assignment publish and after updates | Reports readiness state and clear gaps | +| `Prepare-LearningRoomTemplate.ps1` | Template preparation operations | Script output + repository checks | Before go-live if prep needed | Required template prep completes without hidden failures | +| `Invoke-LearningRoomEndToEndTest.ps1` | Full-scripted QA helper path | Script output and referenced artifacts | Optional preflight or regression validation | End-to-end script executes expected checks | +| `Add-AutograderSafeguards.ps1` and `Fix-AutograderComments.ps1` | Autograder hardening utilities | Script output + workflow behavior | As needed during defects/fixes | Safeguards/comments behavior aligns with expected feedback quality | + +## Phase 8 - Final Sign-Off (Podcast-Excluded Release Gate) + +Use this checklist for final decision. For every item, complete the listed verification steps and record evidence before checking the box. + +- [ ] Registration intake path tested from public page to welcome comment. + Verification steps: + 1. Execute Phase 1 Step 1 and Step 3 with a test registration. + 2. Capture the public entry point, issue creation, and final welcome comment evidence. + 3. Confirm labels and comment content match expected behavior in the QA Validation Contract. + Why this matters: this proves the first learner touchpoint works end to end. + +- [ ] Registration duplicate handling validated. + Verification steps: + 1. Execute Phase 1 Step 4 duplicate scenario. + 2. Confirm duplicate issue closes automatically and references the original. + 3. Record issue links and labels in QA notes. + Why this matters: duplicate control prevents noisy intake and manual cleanup overhead. + +- [ ] Registration CSV and roster sync validated. + Verification steps: + 1. Execute Phase 1 Step 5. + 2. Download `registration-data` artifact and verify the expected test row. + 3. Confirm roster sync updates only when underlying data changes. + Why this matters: operations teams depend on accurate roster exports for cohort management. + +- [ ] Learning Room template sync to GitHub template repository validated. + Verification steps: + 1. Execute Phase 2 Step 6. + 2. Confirm sync PR merged (or no-change outcome) and template repo settings remain correct. + 3. Record PR link or no-change script output. + Why this matters: stale template state breaks downstream assignments even when source repo is correct. + +- [ ] Template smoke repository validation completed from latest template state. + Verification steps: + 1. Execute Phase 2 Step 7. + 2. Confirm smoke repo creation, required file inventory, and seed dispatch behavior. + 3. Record script output and retained evidence links. + Why this matters: this is the fastest proof that template consumers get runnable automation. + +- [ ] Template freshness proof completed against latest merged sync PR. + Verification steps: + 1. Execute Phase 2 Step 8. + 2. Compare at least three changed files from sync PR to smoke repo content. + 3. Log exact file comparisons in QA notes. + Why this matters: confirms new cohorts are not launched from outdated template snapshots. + +- [ ] Day 1 assignment configured and validated. + Verification steps: + 1. Execute Phase 3 Step 11. + 2. Verify assignment settings, description, autograder count, and points. + 3. Store screenshot of final assignment configuration page. + Why this matters: Day 1 misconfiguration creates immediate learner friction and grading drift. + +- [ ] Day 2 assignment configured and validated. + Verification steps: + 1. Execute Phase 3 Step 12. + 2. Verify assignment settings, description, autograder count, and points. + 3. Store screenshot of final assignment configuration page. + Why this matters: Day 2 challenge flow and capstone checks depend on exact assignment setup. + +- [ ] Registration form template and required labels validated. + Verification steps: + 1. Execute Phase 0 Step 0.1 and re-check before sign-off. + 2. Confirm `workshop-registration.yml` is current and selectable. + 3. Confirm labels `registration`, `duplicate`, and `waitlist` exist and are active. + Why this matters: the registration workflow cannot route correctly without these baseline objects. + +- [ ] Test student accepted both assignments and repos created. + Verification steps: + 1. Execute Phase 4 Step 14. + 2. Confirm two private repos are created for Day 1 and Day 2. + 3. Record both repository URLs in completion notes. + Why this matters: acceptance and repo provisioning are required before challenge QA can begin. + +- [ ] Full chapter and appendix walkthrough completed and tracked. + Verification steps: + 1. Execute Phase 5 Step 16 using the per-file verification routine. + 2. Ensure every required chapter and appendix checkbox is either complete or tied to a logged defect. + 3. Confirm no file in the required list is left unreviewed. + Why this matters: curriculum defects can invalidate otherwise healthy automation. + +- [ ] Supporting non-chapter content walkthrough completed and tracked. + Verification steps: + 1. Execute Phase 5 Step 17 using the section verification routine. + 2. Resolve or log all cross-document inconsistencies. + 3. Confirm all supporting-doc checkboxes are complete or defect-linked. + Why this matters: learners rely on these docs during setup and troubleshooting. + +- [ ] Challenge 1 and Challenge 10 seeding validated. + Verification steps: + 1. Execute Phase 4 Step 15. + 2. Confirm seeded issues appear in Day 1 and Day 2 test repos. + 3. Capture issue links for both seeded starting points. + Why this matters: seeding failures block both student journey entry paths. + +- [ ] Full Day 1 student path (1 to 9) completed. + Verification steps: + 1. Execute Phase 6 Day 1 walkthrough across Challenges 1-9. + 2. Confirm progression behavior after each issue closure. + 3. Fill Day 1 rows in Challenge Tracking Log with evidence links. + Why this matters: Day 1 is the foundational workflow and must be dependable for all learners. + +- [ ] Full Day 2 student path (10 to 16) completed. + Verification steps: + 1. Execute Phase 6 Day 2 walkthrough across Challenges 10-16. + 2. Confirm Day 2 autograder behavior for 10, 14, and 16. + 3. Fill Day 2 rows in Challenge Tracking Log with evidence links. + Why this matters: Day 2 validates local workflow, review quality, and capstone readiness. + +- [ ] All bonus challenges A to E tracked with status and evidence or deferral reason. + Verification steps: + 1. Execute Phase 6 Bonus path walkthrough. + 2. Mark each bonus row Pass, Fail, or Deferred with rationale. + 3. Attach evidence link or deferral reason for all five bonus items. + Why this matters: optional learner paths still require QA accountability. + +- [ ] Challenge reliability and failure-mode coverage completed for all challenge families. + Verification steps: + 1. Execute the full Challenge Reliability and Failure-Mode Coverage section. + 2. Validate at least one happy path and one variation path per challenge family. + 3. Confirm recovery behavior is tested, not assumed. + Why this matters: production reliability is defined by recovery from failure paths, not only happy-path success. + +- [ ] Student-visible expected state map was verified at each stage. + Verification steps: + 1. Execute the Student-visible expected state map cross-check. + 2. Compare observed state to each stage row in the table. + 3. Log any mismatch as a defect before sign-off. + Why this matters: this verifies the learner experience directly, not just backend workflow success. + +- [ ] Recovery/reset playbook validated with at least one Level 2 restore test. + Verification steps: + 1. Execute Student recovery and reset playbook Level 2 flow. + 2. Confirm restored files are proposed through branch and PR evidence. + 3. Record restore test repository, branch, and PR links. + Why this matters: facilitators need a proven restoration path during live delivery incidents. + +- [ ] Aria, progression, and autograder workflows validated with evidence. + Verification steps: + 1. Execute checks in the Workflow and Automation Validation Matrix for `pr-validation-bot.yml`, `student-progression.yml`, and all autograder workflows. + 2. Capture one pass and one actionable-fail evidence sample where applicable. + 3. Confirm feedback is clear enough for student self-recovery. + Why this matters: these workflows are the core automated coaching and grading systems. + +- [ ] Open defects documented with owner and due date. + Verification steps: + 1. Review QA notes for all unresolved findings. + 2. Ensure each defect has severity, owner, and due date. + 3. Confirm blocker defects are explicitly marked for release decision. + Why this matters: unresolved defects without ownership are operational risk hidden as "known issues." + +- [ ] Release owner signs go or no-go decision. + Verification steps: + 1. Confirm all required checklist items above are complete or have explicit risk acceptance. + 2. Populate Completion Output Template with final links and outcomes. + 3. Capture release owner decision (Go or No-Go) with approver name and date. + Why this matters: formal accountability prevents ambiguous launch decisions. + +## Troubleshooting and Rollback Quick Actions + +Use this section when a blocker appears during QA. + +1. Registration invite automation issue: + - Step 1: Confirm `CLASSROOM_ORG_ADMIN_TOKEN` and `CLASSROOM_ORG` values are present and correctly scoped. + - Step 2: If automation is still failing, disable org invite automation by clearing `CLASSROOM_ORG`. + - Step 3: Continue registration flow with manual classroom invite process. + - Verify: registration workflow still posts welcome response and assignment links as configured. + +2. Seeding failure: + - Step 1: Re-run seeding script with explicit repository slug and assignee. + - Step 2: Confirm target repo exists and Actions are enabled. + - Step 3: Confirm template workflow inventory includes seeding dependencies. + - Verify: expected challenge issue appears and is assigned correctly. + +3. Progression not creating next issue: + - Step 1: Confirm current challenge issue was closed, not left open with comment only. + - Step 2: Confirm `student-progression.yml` exists in target repository and has successful run history. + - Step 3: Re-dispatch progression workflow if needed. + - Verify: next challenge issue appears with correct numbering. + +4. Autograder mismatch: + - Step 1: Re-check exact autograder command/settings definitions in [admin/classroom/autograding-setup.md](classroom/autograding-setup.md). + - Step 2: Trigger known-fail and known-pass scenarios for the affected autograder. + - Step 3: Compare observed output with expected rubric behavior. + - Verify: fail messages are actionable and pass state is reachable with correct student behavior. + +Escalation rule: + +1. If blocker persists after one remediation cycle, log defect with owner and ETA. +2. Continue with unaffected phases only when blocker impact is clearly isolated. + +Why this matters: + +- Fast, repeatable recovery protects cohort timelines and prevents hidden release risk. + +## Completion Output Template (Copy into QA Issue) + +Before publishing the completion output: + +1. Confirm all required Phase 8 checklist items are complete or explicitly risk-accepted. +2. Ensure every section below includes links, not placeholders. +3. Attach defect list with owner and due date for any unresolved findings. +4. Capture final approver and decision timestamp. + +Why this matters: + +- This output is the release audit record and must be independently reviewable. + +```text +Runbook Version: admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md +Date: +QA Owner: +Facilitator Account: +Test Student Account: + +Registration QA: +- Happy path: +- Duplicate path: +- Waitlist path: +- CSV export: +- Roster sync: + +Classroom QA: +- Day 1 assignment URL: +- Day 2 assignment URL: +- Day 1 repo URL: +- Day 2 repo URL: + +Challenge QA: +- Chapter walkthrough complete (00-21 + Appendix A-Z): +- Supporting non-chapter content walkthrough complete: +- Day 1 complete (1-9): +- Day 2 complete (10-16): +- Challenge reliability/failure-mode coverage complete: +- Student-visible expected state map verified: +- Recovery Level 2 restore test completed: +- Bonus A status: +- Bonus B status: +- Bonus C status: +- Bonus D status: +- Bonus E status: + +Automation QA: +- Registration workflow: +- Registration form/label setup: +- Aria: +- Content validation: +- Progression: +- Skills progression: +- Autograders: +- Seeding scripts: + +Open Defects: +- [ID] Severity | Owner | ETA + +Release Decision: +- Go / No-Go +- Approver: +``` + +## What This Runbook Replaces + +This runbook is the operator-facing execution path that unifies registration, deployment, and end-to-end challenge QA. + +It does not replace source documents. It sequences them into one practical checklist so a single facilitator can execute and validate the full system without context switching across multiple folders. \ No newline at end of file diff --git a/admin/qa-bundle/admin/REGISTRATION-QUICKSTART.md b/admin/qa-bundle/admin/REGISTRATION-QUICKSTART.md new file mode 100644 index 0000000..36ecc25 --- /dev/null +++ b/admin/qa-bundle/admin/REGISTRATION-QUICKSTART.md @@ -0,0 +1,79 @@ +# Registration Automation Quickstart (Facilitator) + +Use this when you need to enable registration plus classroom API automation quickly. + +For full background and troubleshooting, use [REGISTRATION-ADMIN.md](REGISTRATION-ADMIN.md). + +## 5-Minute Setup + +1. Create an admin token from a facilitator account with organization invitation permissions. +2. In repository settings, add secret: + - `CLASSROOM_ORG_ADMIN_TOKEN` +3. In repository settings, add variables: + - `CLASSROOM_ORG` + - `CLASSROOM_DAY1_ASSIGNMENT_URL` + - `CLASSROOM_DAY2_ASSIGNMENT_URL` +4. Save all values. +5. Submit one test registration issue from a non-member test account. + +## Copy/Paste Settings Template + +Use this checklist while entering repository settings values. + +### Repository Secret + +| Name | Value to paste | +|---|---| +| CLASSROOM_ORG_ADMIN_TOKEN | PASTE_ADMIN_TOKEN_HERE | + +### Repository Variables + +| Name | Value to paste | +|---|---| +| CLASSROOM_ORG | Community-Access-Classroom | +| CLASSROOM_DAY1_ASSIGNMENT_URL | https://classroom.github.com/a/REPLACE_DAY1_ID | +| CLASSROOM_DAY2_ASSIGNMENT_URL | https://classroom.github.com/a/REPLACE_DAY2_ID | + +### Before You Save + +- Confirm there are no extra spaces before or after values. +- Confirm both assignment URLs open correctly in a logged-in browser. +- Confirm the org name matches exactly, including capitalization. + +## Expected Result (Happy Path) + +After the test issue is opened and capacity is available: + +1. Registration confirmation comment is posted. +2. Organization invite is sent (or detected as already pending/member). +3. Day 1 and Day 2 assignment links appear in the confirmation comment. +4. `registration` label is applied. + +## Fast Verification Checklist + +- [ ] Test user received or already had organization invite +- [ ] Confirmation comment includes assignment links +- [ ] Duplicate submission closes automatically with duplicate message +- [ ] Waitlist behavior still works when capacity is full + +## Rollback (Immediate) + +If anything behaves unexpectedly, disable classroom API automation without stopping registration: + +1. Remove repository secret `CLASSROOM_ORG_ADMIN_TOKEN`, or +2. Clear repository variable `CLASSROOM_ORG` + +The registration workflow will continue standard confirmation, capacity checks, and CSV export. + +## Day-Of Operations + +1. Keep [REGISTRATION-ADMIN.md](REGISTRATION-ADMIN.md) open. +2. Watch Actions runs for `registration.yml` after each new registration. +3. Spot-check one confirmation comment every few runs. +4. If failures appear, use rollback and continue manual classroom invite flow. + +## Privacy Reminder + +- Registration issues are public in this repository. +- CSV export includes names and email addresses and is stored as a workflow artifact. +- `student-roster.json` sync stores non-PII operational data only. \ No newline at end of file diff --git a/admin/qa-bundle/admin/classroom/README.md b/admin/qa-bundle/admin/classroom/README.md new file mode 100644 index 0000000..e4ddb6e --- /dev/null +++ b/admin/qa-bundle/admin/classroom/README.md @@ -0,0 +1,35 @@ +# Classroom Copy-Paste Pack + +This folder is a facilitator-focused copy-paste pack for GitHub Classroom setup. + +Use these files when you need to quickly configure assignments without jumping between multiple folders. + +## What Is Included + +- `day1-assignment-copy-paste.md` - Day 1 assignment body ready to paste into Classroom. +- `day2-assignment-copy-paste.md` - Day 2 assignment body ready to paste into Classroom. +- `autograding-setup.md` - Exact Day 1 and Day 2 autograding entries, validation steps, and troubleshooting. +- `seeding-ops.md` - Post-acceptance scripts to seed challenges and peer simulation content. +- `live-facilitation-flow.md` - Single-run checklist for creating assignments, enabling autograding, publishing, seeding, and validating. + +## Recommended Setup Order + +1. Create the Classroom and import roster from `classroom/README.md`. +2. Create Day 1 assignment and paste content from `day1-assignment-copy-paste.md`. +3. Configure Day 1 tests using `autograding-setup.md`. +4. Create Day 2 assignment and paste content from `day2-assignment-copy-paste.md`. +5. Configure Day 2 tests using `autograding-setup.md`. +6. After each student accepts, run seeding commands from `seeding-ops.md`. +7. Use `live-facilitation-flow.md` during setup day to execute the full flow without missing steps. + +## Source of Truth + +This pack is derived from: + +- `classroom/assignment-day1-you-belong-here.md` +- `classroom/assignment-day2-you-can-build-this.md` +- `classroom/autograding-day1.json` +- `classroom/autograding-day2.json` +- `scripts/classroom/*.ps1` + +If those source files change, update this folder to keep the copy-paste flow accurate. diff --git a/admin/qa-bundle/admin/classroom/autograding-setup.md b/admin/qa-bundle/admin/classroom/autograding-setup.md new file mode 100644 index 0000000..036f14a --- /dev/null +++ b/admin/qa-bundle/admin/classroom/autograding-setup.md @@ -0,0 +1,211 @@ +# Autograding Setup and Verification + +This guide makes Classroom autograding setup repeatable and reliable for facilitators. + +## Scope + +- Day 1 tests come from `classroom/autograding-day1.json` +- Day 2 tests come from `classroom/autograding-day2.json` +- All entries below are copy-accurate from those files + +## UI Entry Rules (Use for Every Test) + +For each test you add in Classroom: + +- Set **Test name** exactly as shown below +- Set **Run command** exactly as shown below +- Set **Comparison** to `exact` +- Leave **Setup**, **Input**, and **Expected output** empty unless noted +- Set **Timeout** and **Points** exactly as shown below + +Do not paste raw JSON into the UI. Add tests one by one. + +## Day 1 Autograding Tests + +### Test 1 + +- Test name: `Challenge 2: Issue Filed` +- Run command: + +```bash +gh issue list --repo $GITHUB_REPOSITORY --author $GITHUB_ACTOR --state all --json number --jq 'length' | xargs test 0 -lt +``` + +- Comparison: `exact` +- Timeout: `10` +- Points: `10` + +### Test 2 + +- Test name: `Challenge 5: Commit Exists` +- Run command: + +```bash +git log --oneline --all --author=$GITHUB_ACTOR | head -1 | grep -q '.' +``` + +- Comparison: `exact` +- Timeout: `10` +- Points: `10` + +### Test 3 + +- Test name: `Challenge 6: PR with Issue Link` +- Run command: + +```bash +gh pr list --repo $GITHUB_REPOSITORY --author $GITHUB_ACTOR --state all --json body --jq '.[0].body' | grep -iq 'closes\|fixes\|resolves' +``` + +- Comparison: `exact` +- Timeout: `10` +- Points: `15` + +### Test 4 + +- Test name: `Challenge 7: No Conflict Markers` +- Run command: + +```bash +! grep -rn '<<<<<<< \|======= \|>>>>>>> ' docs/ 2>/dev/null +``` + +- Comparison: `exact` +- Timeout: `10` +- Points: `15` + +## Day 2 Autograding Tests + +### Test 1 + +- Test name: `Challenge 10: Go Local - Commit on Branch` +- Run command: + +```bash +git log --oneline origin/main..HEAD 2>/dev/null | head -1 | grep -q '.' || git branch -r --list 'origin/*' | grep -v main | head -1 | xargs -I{} git log --oneline origin/main..{} | head -1 | grep -q '.' +``` + +- Comparison: `exact` +- Timeout: `10` +- Points: `15` + +### Test 2 + +- Test name: `Challenge 14: Template Remix - Custom Issue Template Exists` +- Run command: + +```bash +find .github/ISSUE_TEMPLATE -name '*.yml' ! -name 'challenge-*.yml' ! -name 'bonus-*.yml' ! -name 'config.yml' 2>/dev/null | head -1 | grep -q '.' +``` + +- Comparison: `exact` +- Timeout: `10` +- Points: `15` + +### Test 3 + +- Test name: `Challenge 14: Template Remix - Template Has Required Fields` +- Run command: + +```bash +TEMPLATE=$(find .github/ISSUE_TEMPLATE -name '*.yml' ! -name 'challenge-*.yml' ! -name 'bonus-*.yml' ! -name 'config.yml' 2>/dev/null | head -1); grep -q '^name:' "$TEMPLATE" && grep -q '^description:' "$TEMPLATE" +``` + +- Comparison: `exact` +- Timeout: `10` +- Points: `10` + +### Test 4 + +- Test name: `Challenge 16: Build Your Agent - Agent File Exists` +- Run command: + +```bash +find agents community-agents -name '*.md' 2>/dev/null | head -1 | grep -q '.' +``` + +- Comparison: `exact` +- Timeout: `10` +- Points: `10` + +### Test 5 + +- Test name: `Challenge 16: Build Your Agent - Agent Has Frontmatter` +- Run command: + +```bash +AGENT=$(find agents community-agents -name '*.md' 2>/dev/null | head -1); head -1 "$AGENT" | grep -q '^---' +``` + +- Comparison: `exact` +- Timeout: `10` +- Points: `10` + +### Test 6 + +- Test name: `Challenge 16: Build Your Agent - Agent Has Responsibilities and Guardrails` +- Run command: + +```bash +AGENT=$(find agents community-agents -name '*.md' 2>/dev/null | head -1); grep -qi '## responsibilities\|## what this agent does' "$AGENT" && grep -qi '## guardrails\|## limitations\|## boundaries' "$AGENT" +``` + +- Comparison: `exact` +- Timeout: `10` +- Points: `15` + +## Hardening Checklist Before Cohort Start + +1. Add all tests and save assignment. +2. Confirm test count: + - Day 1 has 4 tests + - Day 2 has 6 tests +3. Confirm point totals: + - Day 1 total = 50 + - Day 2 total = 75 +4. Use a test student account to accept each assignment. +5. Trigger one known pass on each assignment. +6. Trigger one known fail on each assignment and confirm feedback appears. +7. Confirm rerun passes after fix. +8. Capture one screenshot of pass and one of fail for facilitator reference. + +## Fast Validation Scenarios + +### Day 1 quick checks + +- Pass check: open an issue, make a commit, open a PR with `Closes #`, ensure no conflict markers remain in `docs/`. +- Fail check: open a PR without `Closes`, `Fixes`, or `Resolves` in the body. + +### Day 2 quick checks + +- Pass check: create one non-main commit, add a custom issue template with `name:` and `description:`, add an agent markdown file with frontmatter and required sections. +- Fail check: create an agent file without a `## Responsibilities` section. + +## Troubleshooting + +### Test stays red after student fix + +1. Confirm student pushed a new commit to the same PR branch. +2. Open PR checks and inspect the failing command output. +3. Verify required text is in the file body, not only in issue comments. + +### Challenge 14 tests fail unexpectedly + +- Verify template filename is `.yml`. +- Verify it is under `.github/ISSUE_TEMPLATE`. +- Verify filename does not match `challenge-*.yml`, `bonus-*.yml`, or `config.yml`. + +### Challenge 16 section check fails + +- Ensure headings use markdown heading syntax (for example `## Responsibilities`). +- Ensure guardrail heading uses one accepted form: + - `## Guardrails` + - `## Limitations` + - `## Boundaries` + +## Keep This Guide Synced + +If autograding JSON changes, update this file in the same pull request: + +- `classroom/autograding-day1.json` +- `classroom/autograding-day2.json` diff --git a/admin/qa-bundle/admin/classroom/day1-assignment-copy-paste.md b/admin/qa-bundle/admin/classroom/day1-assignment-copy-paste.md new file mode 100644 index 0000000..0b4bda9 --- /dev/null +++ b/admin/qa-bundle/admin/classroom/day1-assignment-copy-paste.md @@ -0,0 +1,90 @@ +# Day 1 Assignment Copy-Paste + +Use this file to configure Assignment 1 in GitHub Classroom. + +## Assignment Settings + +- Title: `You Belong Here` +- Type: `Individual` +- Visibility: `Private` +- Template repository: `Community-Access/learning-room-template` +- Grant students admin access: `No` +- Enable feedback pull requests: `Yes` +- Deadline: End of Day 1 or your cohort-specific date + +## Paste Into Assignment Description + +Copy everything inside the block below into the Classroom assignment description field. + +```markdown +# Assignment 1: You Belong Here + +Welcome to Git Going with GitHub! This is your private learning repository for Day 1. Everything you do here is yours - experiment freely. + +## What You Will Do Today + +During the live Day 1 core path, you will practice the skills needed to make your first browser-based GitHub contribution. If the room needs more time, later challenges can continue during open lab time or after the event. + +- Navigate a real GitHub repository using your screen reader +- File your first issue describing something you noticed +- Communicate with teammates using @mentions and comments +- Create a branch to work in safely +- Make your first commit to a file +- Open a pull request linking your work to an issue +- Learn how merge conflicts work, with live support if time allows +- Reflect on open source culture and communication, live or asynchronously +- Merge a pull request into the main branch, or leave with clear next steps to finish it + +## Challenges + +Complete these challenges in order. Each one builds on the previous. When you close a challenge issue, the Student Progression Bot automatically opens your next challenge. The live agenda prioritizes Challenges 1-6; Challenges 7-9 are available as stretch or async follow-up. + +| Challenge | What You Do | Chapter | +|---|---|---| +| 1. Find Your Way Around | Explore the repository structure and locate key files | [Chapter 3](https://github.com/Community-Access/git-going-with-github/blob/main/docs/03-navigating-repositories.md) | +| 2. File Your First Issue | Create an issue describing something you noticed | [Chapter 5](https://github.com/Community-Access/git-going-with-github/blob/main/docs/05-working-with-issues.md) | +| 3. Join the Conversation | Mention a teammate or bot using @mentions | [Chapter 5](https://github.com/Community-Access/git-going-with-github/blob/main/docs/05-working-with-issues.md) | +| 4. Branch Out | Create a feature branch for your work | [Chapter 4](https://github.com/Community-Access/git-going-with-github/blob/main/docs/04-the-learning-room.md) | +| 5. Make Your Mark | Edit a file and commit with a clear message | [Chapter 4](https://github.com/Community-Access/git-going-with-github/blob/main/docs/04-the-learning-room.md) | +| 6. Open Your First Pull Request | Open a PR that references an issue with `Closes #N` | [Chapter 6](https://github.com/Community-Access/git-going-with-github/blob/main/docs/06-working-with-pull-requests.md) | +| 7. Survive a Merge Conflict | Understand and fix conflict markers | [Chapter 7](https://github.com/Community-Access/git-going-with-github/blob/main/docs/07-merge-conflicts.md) | +| 8. The Culture Layer | Reflect on community norms and communication | [Chapter 8](https://github.com/Community-Access/git-going-with-github/blob/main/docs/08-open-source-culture.md) | +| 9. Merge Day | Get your PR reviewed, approved, and merged | [Chapter 10](https://github.com/Community-Access/git-going-with-github/blob/main/docs/10-notifications-and-day-1-close.md) | + +## Autograded Challenges + +Challenges 2, 5, 6, and 7 have automated checks that run when you push or open a PR: + +- **Challenge 2:** Verifies you have filed at least one issue +- **Challenge 5:** Verifies at least one commit exists on a non-default branch +- **Challenge 6:** Verifies your PR body contains `Closes`, `Fixes`, or `Resolves` +- **Challenge 7:** Verifies no merge conflict markers remain in `docs/` + +The autograder posts feedback as a PR comment. If a check fails, read the feedback and push an update. + +## Evidence + +Each challenge has an issue that the Student Progression Bot creates for you. Complete the challenge, leave a comment with your evidence, and close the issue to unlock the next one. + +## If You Get Stuck + +Every chapter has an "If You Get Stuck" section with specific troubleshooting steps. Start there. + +You can also: +- Ask your assigned buddy or study group +- Post a question on the issue thread +- Mention `@aria-bot` in a comment for a workspace check +- Ask a facilitator for help - that is what they are here for + +## After Day 1 + +When you complete all 9 challenges, you have the foundation for everything in Day 2 - or for contributing to any open source project on your own. These skills are yours permanently. + +**Continuing to Day 2?** See the [Day 2 assignment](https://github.com/Community-Access/git-going-with-github/blob/main/classroom/assignment-day2-you-can-build-this.md) for what comes next. + +**Day 1 is your only day?** Everything you learned today is complete and self-contained. See the [Next Steps guide](https://github.com/Community-Access/git-going-with-github/blob/main/docs/21-next-steps.md) for how to continue your GitHub journey independently. + +## Bonus Challenges + +If you finish early, check the [Challenges page](https://github.com/Community-Access/git-going-with-github/blob/main/docs/CHALLENGES.md) for bonus challenges A through E. +``` diff --git a/admin/qa-bundle/admin/classroom/day2-assignment-copy-paste.md b/admin/qa-bundle/admin/classroom/day2-assignment-copy-paste.md new file mode 100644 index 0000000..eb249f9 --- /dev/null +++ b/admin/qa-bundle/admin/classroom/day2-assignment-copy-paste.md @@ -0,0 +1,91 @@ +# Day 2 Assignment Copy-Paste + +Use this file to configure Assignment 2 in GitHub Classroom. + +## Assignment Settings + +- Title: `You Can Build This` +- Type: `Individual` +- Visibility: `Private` +- Template repository: `Community-Access/learning-room-template` +- Grant students admin access: `No` +- Enable feedback pull requests: `Yes` +- Deadline: One week after Day 2 or your cohort-specific date + +## Paste Into Assignment Description + +Copy everything inside the block below into the Classroom assignment description field. + +```markdown +# Assignment 2: You Can Build This + +Welcome back - or welcome for the first time! Day 2 moves from the browser to your local machine and introduces real-world development workflows. + +## Joining Day 2 Without Day 1? + +You do not need to have attended Day 1 to succeed today. If you already have GitHub fundamentals (navigating repos, filing issues, opening PRs, reviewing code), you have the same foundation as Day 1 participants. + +Before starting the challenges below, verify your readiness with the [Day 2 Quick Start](https://github.com/Community-Access/git-going-with-github/blob/main/admin/DAY2_QUICK_START.md) guide. It takes about 30 minutes and confirms you have the accounts, tools, and skills needed. + +## What You Will Do Today + +During the live Day 2 core path, you will move from browser-based GitHub to local contribution work in VS Code. Some advanced challenges are intentionally available as stretch or async follow-up so participants and remote cohorts can continue at a sustainable pace. + +- Clone a repository and work with Git locally +- Push a branch and open a PR from your local machine +- Review a classmate's code and give constructive feedback +- Use GitHub Copilot as a collaborative tool +- Create or review a custom issue template, if time allows +- Fork a real repository and prepare a cross-repo contribution path +- Explore accessibility agents and how they work +- Start your own agent or capstone idea, with a path to finish asynchronously + +## Challenges + +Complete these challenges in order. Each one builds on the previous. The live agenda prioritizes Challenges 10-13 and agent discovery; Challenges 14-16 can be completed during lab time or after the event. + +| Challenge | What You Do | Chapter | +|---|---|---| +| 10. Go Local | Clone, branch, edit, commit, and push using local Git | [Chapter 14](https://github.com/Community-Access/git-going-with-github/blob/main/docs/14-git-in-practice.md) | +| 11. Open a Day 2 PR | Open a PR from your locally-pushed branch | [Chapter 15](https://github.com/Community-Access/git-going-with-github/blob/main/docs/15-code-review.md) | +| 12. Review Like a Pro | Review a classmate's PR with specific, constructive feedback | [Chapter 15](https://github.com/Community-Access/git-going-with-github/blob/main/docs/15-code-review.md) | +| 13. AI as Your Copilot | Use Copilot to improve documentation and evaluate its output | [Chapter 16](https://github.com/Community-Access/git-going-with-github/blob/main/docs/16-github-copilot.md) | +| 14. Template Remix | Create a custom YAML issue template | [Chapter 17](https://github.com/Community-Access/git-going-with-github/blob/main/docs/17-issue-templates.md) | +| 15. Meet the Agents | Explore and run agents from the accessibility-agents repo | [Chapter 19](https://github.com/Community-Access/git-going-with-github/blob/main/docs/19-accessibility-agents.md) | +| 16. Build Your Agent (Capstone) | Design and submit an original agent with responsibilities and guardrails | [Chapter 20](https://github.com/Community-Access/git-going-with-github/blob/main/docs/20-build-your-agent.md) | + +## Autograded Challenges + +Challenges 10, 14, and 16 have automated checks that run when you open a PR: + +- **Challenge 10:** Verifies at least one commit exists on a non-default branch +- **Challenge 14:** Verifies your YAML template has required `name` and `description` fields +- **Challenge 16:** Verifies your agent file has valid frontmatter, responsibilities, and guardrails + +The autograder posts feedback as a PR comment. If a check fails, read the feedback and push an update. + +## Evidence + +Each challenge has an issue template in the Learning Room. Open the matching issue, complete the challenge, and post your evidence as described in the issue. Challenges 10, 14, and 16 also have automated checks that post PR feedback when you push or open a pull request; use those bot comments as guidance, then keep your human evidence in the challenge issue. + +## If You Get Stuck + +Every chapter has an "If You Get Stuck" section with specific troubleshooting steps. Start there. + +The [solutions directory](https://github.com/Community-Access/git-going-with-github/tree/main/docs/solutions) has reference solutions for every challenge. These show annotated examples of what a completed challenge looks like. + +## Fork Workflow (Challenges 15-16) + +For the capstone challenges, you will work with the [accessibility-agents](https://github.com/Community-Access/accessibility-agents) repository: + +1. Fork the repository to your account +2. Clone your fork locally +3. Create a branch for your work +4. Open a PR from your fork back to the original + +See [Chapter 18](https://github.com/Community-Access/git-going-with-github/blob/main/docs/18-fork-and-contribute.md) for the full fork workflow. If forking is new to you, [Chapter 6: Working with Pull Requests](https://github.com/Community-Access/git-going-with-github/blob/main/docs/06-working-with-pull-requests.md) covers the fundamentals. + +## Bonus Challenges + +If you finish early, check the [Challenges page](https://github.com/Community-Access/git-going-with-github/blob/main/docs/CHALLENGES.md) for bonus challenges. +``` diff --git a/admin/qa-bundle/admin/classroom/live-facilitation-flow.md b/admin/qa-bundle/admin/classroom/live-facilitation-flow.md new file mode 100644 index 0000000..ea811d7 --- /dev/null +++ b/admin/qa-bundle/admin/classroom/live-facilitation-flow.md @@ -0,0 +1,96 @@ +# Live Facilitation Flow Checklist + +Use this checklist when setting up a new cohort so you can run the full Classroom workflow in one pass. + +## Phase 1: Classroom and Roster + +- [ ] Open classroom.github.com and create or select the target classroom. +- [ ] Confirm organization is correct (Community-Access). +- [ ] Import roster CSV and verify expected usernames appear. +- [ ] Confirm template repository is available: `Community-Access/learning-room-template`. + +## Phase 2: Create Day 1 Assignment + +- [ ] Click New assignment. +- [ ] Set title to You Belong Here. +- [ ] Set type to Individual. +- [ ] Set visibility to Private. +- [ ] Set starter template repository to `Community-Access/learning-room-template`. +- [ ] Set Grant students admin access to No. +- [ ] Set Enable feedback pull requests to Yes. +- [ ] Set deadline for your cohort. +- [ ] Copy description from `day1-assignment-copy-paste.md` and paste into Classroom. + +## Phase 3: Configure Day 1 Autograding + +- [ ] Open `autograding-setup.md`. +- [ ] Add all Day 1 tests exactly as listed. +- [ ] Verify Day 1 test count is 4. +- [ ] Verify Day 1 point total is 50. +- [ ] Save assignment. + +## Phase 4: Create Day 2 Assignment + +- [ ] Click New assignment. +- [ ] Set title to You Can Build This. +- [ ] Set type to Individual. +- [ ] Set visibility to Private. +- [ ] Set starter template repository to `Community-Access/learning-room-template`. +- [ ] Set Grant students admin access to No. +- [ ] Set Enable feedback pull requests to Yes. +- [ ] Set deadline for your cohort. +- [ ] Copy description from `day2-assignment-copy-paste.md` and paste into Classroom. + +## Phase 5: Configure Day 2 Autograding + +- [ ] Open `autograding-setup.md`. +- [ ] Add all Day 2 tests exactly as listed. +- [ ] Verify Day 2 test count is 6. +- [ ] Verify Day 2 point total is 75. +- [ ] Save assignment. + +## Phase 6: Publish and Share + +- [ ] Publish Day 1 assignment. +- [ ] Publish Day 2 assignment. +- [ ] Copy Day 1 invite link and store in facilitator notes. +- [ ] Copy Day 2 invite link and store in facilitator notes. +- [ ] Update agenda docs/placeholders with final invite links. + +## Phase 7: First Student Acceptance and Seeding + +After a student accepts, run these commands from the repository root. + +### Day 1 seeding + +```powershell +scripts/classroom/Seed-LearningRoomChallenge.ps1 -Repository Community-Access-Classroom/learning-room-studentname -Challenge 1 -Assignee studentname +``` + +### Day 2 seeding + +```powershell +scripts/classroom/Seed-LearningRoomChallenge.ps1 -Repository Community-Access-Classroom/learning-room-studentname -Challenge 10 -Assignee studentname +``` + +### Peer simulation seeding + +```powershell +scripts/classroom/Seed-PeerSimulation.ps1 -Repository Community-Access-Classroom/learning-room-studentname -StudentUsername studentname +``` + +## Phase 8: Verification Gate + +- [ ] Confirm challenge issue exists after seeding. +- [ ] Confirm Student Progression workflow run appears in Actions. +- [ ] Confirm one autograding failure scenario is detected correctly. +- [ ] Confirm one fixed rerun passes. +- [ ] Confirm peer simulation artifacts exist (2 issues + 1 PR). + +## Phase 9: Cohort Readiness Sign-Off + +- [ ] Day 1 and Day 2 assignments published. +- [ ] Invite links validated. +- [ ] Autograding configured and tested. +- [ ] Seeding scripts verified against a test student repo. +- [ ] Facilitator notes updated with links and fallback instructions. diff --git a/admin/qa-bundle/admin/qa-readiness/README.md b/admin/qa-bundle/admin/qa-readiness/README.md new file mode 100644 index 0000000..24deec0 --- /dev/null +++ b/admin/qa-bundle/admin/qa-readiness/README.md @@ -0,0 +1,59 @@ +# QA Readiness Test Pack (Non-Podcast) + +This folder contains local, repeatable QA readiness evidence for deployment, automation setup, challenge reliability coverage, and release-gate integrity. + +## Scope + +Included: + +- Registration workflow readiness checks. +- Classroom deployment and template readiness checks. +- Challenge inventory and reliability-gate coverage checks. +- Runbook and go-live gate integrity checks. +- Existing validation and automation tests under `.github/scripts/__tests__/`. + +Excluded: + +- Podcast generation and podcast validation workflows. + +## Test Entry Point + +Run locally from repository root: + +```powershell +npm run test:automation +``` + +Current test harness executes all Node tests in `.github/scripts/__tests__/*.test.js`. + +## New Unit Tests Added in This QA Pass + +- `.github/scripts/__tests__/qa-readiness-gates.test.js` +- `.github/scripts/__tests__/challenge-reliability-coverage.test.js` +- `.github/scripts/__tests__/registration-workflow-readiness.test.js` + +## Latest Results + +See: + +- [UNIT-TEST-RESULTS-2026-05-08.md](UNIT-TEST-RESULTS-2026-05-08.md) + +## Interpreting Confidence + +Local unit tests provide strong confidence for: + +- Static configuration correctness. +- Presence and structure of workflows/templates/docs. +- Internal consistency across challenge and runbook artifacts. + +Local unit tests do not replace live platform verification for: + +- GitHub Classroom invite acceptance behavior. +- Organization permission edge cases. +- Workflow timing/latency in hosted GitHub Actions. +- Human interpretation and recovery behavior in real challenge execution. + +Use this pack together with: + +- [admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md](../LEARNING-ROOM-E2E-QA-RUNBOOK.md) +- [GO-LIVE-QA-GUIDE.md](../../GO-LIVE-QA-GUIDE.md) diff --git a/admin/qa-bundle/admin/qa-readiness/UNIT-TEST-RESULTS-2026-05-08.md b/admin/qa-bundle/admin/qa-readiness/UNIT-TEST-RESULTS-2026-05-08.md new file mode 100644 index 0000000..dd78769 --- /dev/null +++ b/admin/qa-bundle/admin/qa-readiness/UNIT-TEST-RESULTS-2026-05-08.md @@ -0,0 +1,87 @@ +# Unit Test Results - 2026-05-08 (Non-Podcast Scope) + +## Execution Context + +- Command: `npm run test:automation` +- Runtime: local PowerShell terminal +- Workspace: `s:/code/git-going-with-github` +- Scope: non-podcast readiness and reliability checks + +## Expected Outcome + +- Unit tests complete successfully. +- No failing tests in readiness-critical suites. +- Added readiness/reliability tests validate current runbook and release-gate language. + +## Proven Outcome + +- Total tests: 99 +- Passed: 99 +- Failed: 0 +- Skipped: 0 + +Result: PASS + +Revalidation: + +- Full rerun after adding student reset/recovery automation also passed at 99/99. + +## What Was Validated by This Run + +1. Challenge inventory and numbering consistency: +- 16 core challenge templates +- 5 bonus templates +- Complete numbering/lettering coverage + +2. Challenge quality gates: +- Required evidence fields and troubleshooting guidance +- Core and bonus template quality checks + +3. Classroom setup consistency: +- Assignment docs and autograding JSON integrity +- Required scripts and template files present +- Classroom README deployment section coverage + +4. Workflow configuration readiness: +- Concurrency settings in key workflows +- Critical permissions in bot/progression workflows + +5. Registration readiness: +- Workflow logic includes registration, duplicate, and waitlist paths +- Registration issue form template exists + +6. QA gate integrity: +- E2E runbook includes no-go gates and reliability matrix sections +- Top-level go-live guide includes non-podcast readiness gate checks + +## Defects Found During Initial Run and Resolved + +1. Brittle assertion mismatch in new runbook gate test: +- Cause: expected wording did not match final runbook phrasing. +- Fix: updated test to assert actual required phrasing in runbook. + +2. Registration template name assertion too strict: +- Cause: regex did not account for quoted/suffixed template title. +- Fix: relaxed assertion to match real template naming format. + +After fixes, full suite passed. + +## Remaining Risk After Local Unit Tests + +Local unit testing does not fully prove hosted-environment behavior for: + +- GitHub Classroom acceptance timing and repo provisioning. +- Organization-level policy impacts on Actions permissions. +- Bot response latency under GitHub Actions queue pressure. +- Human challenge recovery quality in real student scenarios. + +These are covered by mandatory live gates in: + +- [admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md](../LEARNING-ROOM-E2E-QA-RUNBOOK.md) +- [GO-LIVE-QA-GUIDE.md](../../GO-LIVE-QA-GUIDE.md) + +## Recommendation + +Treat this result as strong local readiness evidence. + +Do not declare final go-live readiness until live environment gates and human reliability gates are also complete. \ No newline at end of file diff --git a/admin/qa-bundle/classroom/HUMAN_TEST_MATRIX.md b/admin/qa-bundle/classroom/HUMAN_TEST_MATRIX.md new file mode 100644 index 0000000..11e4530 --- /dev/null +++ b/admin/qa-bundle/classroom/HUMAN_TEST_MATRIX.md @@ -0,0 +1,216 @@ +# 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: + +```powershell +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: + +```powershell +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. + +1. **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. + +2. **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. + +3. **Challenge 3: Join the Conversation** + - Comment on `Peer Simulation: Welcome Link Needs Context`. + - Include `@aria-bot` in the comment. + - Add a reaction. + - Verify Aria responds if issue-comment workflow permissions allow it. + - Close Challenge 3. + - Verify Challenge 4 appears. + +4. **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. + +5. **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. + +6. **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 Aria posts PR feedback. + - Comment on the peer-simulation PR. + - Close Challenge 6 when ready. + - Verify Challenge 7 appears. + +7. **Challenge 7: Survive a Merge Conflict** + - Run the facilitator conflict script after the student's PR exists: + +```powershell +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. + +8. **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. + +9. **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. + +10. **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. + +11. **Challenge 11: Open a Day 2 PR** + - Open a PR from the locally pushed branch. + - Verify Aria feedback appears. + - Review the peer-simulation PR title and description. + - Close Challenge 11. + - Verify Challenge 12 appears. + +12. **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. + +13. **Challenge 13: AI as Your Copilot** + - Use Copilot to improve `docs/samples/copilot-improvement-before.md` or another document. + - Record what Copilot suggested. + - Record what the student accepted, rejected, or changed. + - Compare the result against the peer-simulation PR or real buddy work. + - Close Challenge 13. + - Verify Challenge 14 appears. + +14. **Challenge 14: Template Remix** + - Create a new non-challenge issue template in `.github/ISSUE_TEMPLATE/`. + - Verify it has `name:` and `description:`. + - Open a PR. + - Verify the issue-template workflow succeeds. + - Close Challenge 14. + - Verify Challenge 15 appears. + +15. **Challenge 15: Meet the Agents** + - Browse `Community-Access/accessibility-agents`. + - Identify at least three agents. + - Run or inspect one agent. + - Compare discoveries with the peer-simulation issue or a real buddy. + - Close Challenge 15. + - Verify Challenge 16 appears. + +16. **Challenge 16: Build Your Agent** + - Fork `Community-Access/accessibility-agents`. + - Create an agent file with frontmatter, responsibilities, and guardrails. + - Open a cross-fork PR. + - Review a peer PR if available; otherwise review the peer-simulation PR and explain what would matter in an agent review. + - Verify capstone workflow feedback in the Learning Room if the agent file is also represented there. + - Close Challenge 16. + +## Bonus Test + +The five bonus challenges are optional and facilitator-reviewed. + +17. **Bonus A: Improve an Existing Agent** + - Choose an existing agent. + - Propose and submit a meaningful improvement. + +18. **Bonus B: Document Your Journey** + - Write a reflection document. + - Verify it is clear and accessible. + +19. **Bonus C: Create a Group Challenge** + - Design a collaborative challenge for a future cohort. + - Confirm it can work with peer simulation or real buddy access. + +20. **Bonus D: Notification Mastery** + - Configure notification settings. + - Document the student's notification strategy. + +21. **Bonus E: Explore Git History Visually** + - Use GitHub Desktop or GitHub.com history views. + - Explain what changed over time. + +## Pass Criteria + +The template is ready only when all of the following are true: + +- Challenge 1 can be seeded. +- Peer simulation artifacts can be seeded. +- Closing Challenge 1 creates Challenge 2. +- Sequential challenge creation works through at least Challenge 5 in smoke testing. +- Challenge 7 can create a real conflict after the student's branch edits the same TODO line. +- Aria PR feedback appears without failing the workflow if GitHub comment APIs are temporarily unavailable. +- Challenges 10, 14, and 16 autograders run and post useful feedback. +- Students can complete all peer tasks using seeded simulation artifacts even without cross-repo buddy access. diff --git a/admin/qa-bundle/classroom/README.md b/admin/qa-bundle/classroom/README.md new file mode 100644 index 0000000..e364436 --- /dev/null +++ b/admin/qa-bundle/classroom/README.md @@ -0,0 +1,451 @@ +# 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](../GO-LIVE-QA-GUIDE.md). 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](../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: + +1. **Aria** (the PR Validation Bot) -- welcomes first-time contributors, validates PR structure, responds to `@aria-bot` help requests, and provides real-time feedback on every push +2. **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 +3. **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 + +```text +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: + | Aria (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 forks Community-Access/accessibility-agents + Opens cross-fork PR (validated by autograder-capstone.yml) +``` + +### 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](../admin/DAY1_AGENDA.md) | +| **Day 2 only** | Participants with GitHub fundamentals | Assignment 2 only | [Day 2 Quick Start](../admin/DAY2_QUICK_START.md) then [Day 2 Agenda](../admin/DAY2_AGENDA.md) | + +Day-2-only participants skip Assignment 1 entirely. They verify readiness using the [Day 2 Quick Start](../admin/DAY2_QUICK_START.md) self-assessment, then accept only the Day 2 invite link. + +### What Is in This Directory + +| File | Purpose | +|---|---| +| [assignment-day1-you-belong-here.md](assignment-day1-you-belong-here.md) | Assignment description for Day 1 (paste into Classroom UI) | +| [assignment-day2-you-can-build-this.md](assignment-day2-you-can-build-this.md) | Assignment description for Day 2 (paste into Classroom UI) | +| [autograding-day1.json](autograding-day1.json) | Test definitions for Day 1 autograder | +| [autograding-day2.json](autograding-day2.json) | Test definitions for Day 2 autograder | +| [grading-guide.md](grading-guide.md) | Facilitator rubric for all 21 challenges | +| [roster-template.csv](roster-template.csv) | Starter CSV for importing student roster | +| [student-progression.yml](student-progression.yml) | Reference copy of the progression bot workflow | +| [HUMAN_TEST_MATRIX.md](HUMAN_TEST_MATRIX.md) | End-to-end human walkthrough for all 16 core and 5 bonus challenges | +| [teardown-checklist.md](teardown-checklist.md) | Post-workshop cleanup steps | +| [../GO-LIVE-QA-GUIDE.md](../GO-LIVE-QA-GUIDE.md) | Final release-readiness guide and checklist | +| [../admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md](../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) -- Aria 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 facilitator account (for example, `accesswatch`) as classroom admin/instructor only +- Use a dedicated test-student account to accept invite links and complete challenge flow +- Avoid using the facilitator account as a student for validation runs - admin permissions can hide real student experience issues + +This keeps grading data clean, avoids permission edge cases, and gives you an accurate end-to-end student test. + +--- + +## Step 1: Create the Classroom + +1. Go to [classroom.github.com](https://classroom.github.com) and sign in with your facilitator account +2. Click **New classroom** +3. Select the **Community-Access** organization (if you do not see it, accept the GitHub Classroom invitation from your org admin) +4. Name the classroom using this pattern: `Git Going - [Cohort Name] - [Month Year]` + - Example: `Git Going - Spring Cohort - March 2026` + - Example: `Git Going - Seattle Accessibility Bootcamp - June 2026` +5. **Skip the TA / co-teacher setup** -- facilitators use organization-level permissions instead +6. Click **Create classroom** + +--- + +## Step 2: Import the Student Roster + +The roster links GitHub usernames to student identities so facilitators can track progress on the classroom dashboard. + +1. Open the classroom you just created +2. Go to **Settings** (gear icon) then **Roster Management** +3. Click **Import from CSV** +4. Upload a completed version of [roster-template.csv](roster-template.csv): + +```csv +identifier,name,email +octocat,The Octocat,octocat@example.com +student-a,Alice Student,alice@example.com +``` + +- The `identifier` column **must** match the student's exact GitHub username +- `name` and `email` are optional but helpful for facilitator reference +- Students not on the roster can still accept; they appear as "unidentified" +- Verify all expected students appear in the roster list +- Students can be added later -- the roster is not locked + +--- + +## Step 3: Create Assignment 1 -- You Belong Here (Day 1) + +This assignment covers Challenges 1 through 9. When a student accepts the invite link, GitHub Classroom creates their private repo from the template. After acceptance, facilitators run `scripts/classroom/Seed-LearningRoomChallenge.ps1` to trigger the Student Progression Bot and create Challenge 1. As the student closes each challenge issue, the bot unlocks the next one. + +**Day-2-only participants skip this assignment entirely.** + +From the classroom dashboard, click **New assignment** and fill in the assignment settings: + +| Setting | Value | +|---|---| +| **Title** | You Belong Here | +| **Type** | Individual | +| **Visibility** | Private (student repos visible only to the student and facilitators) | +| **Template repository** | `Community-Access/learning-room-template` | +| **Grant students admin access** | No | +| **Enable feedback pull requests** | Yes | +| **Deadline** | End of Day 1 (deadline is soft -- late work is still accepted) | + +Then complete the remaining fields: + +1. **Assignment description:** Open [assignment-day1-you-belong-here.md](assignment-day1-you-belong-here.md), copy everything below the HTML metadata comment, and paste it into the description field +2. **Autograding tests:** Open [autograding-day1.json](autograding-day1.json) and add each test entry manually -- for each test in the JSON array, click **Add test**, set the **Test name**, **Run command**, **Comparison**, and **Points** to match the JSON values, and set timeout to 60 seconds per test unless otherwise specified +3. Click **Create assignment** -- this generates your Day 1 invite link + +### What the student experiences (Day 1) + +1. Student clicks the invite link +2. GitHub Classroom creates their private repo (30-60 seconds) +3. Facilitator seeds Challenge 1 (Find Your Way Around) using `student-progression.yml` +4. Student completes the challenge, posts evidence, closes the issue +5. Progression Bot creates Challenge 2 issue with full instructions +6. Student repeats through Challenge 9 (Merge Day) +7. Aria provides real-time feedback on every PR along the way +8. Autograders validate Challenges 4, 5, 6, 7, and 9 automatically + +--- + +## Step 4: Create Assignment 2 -- You Can Build This (Day 2) + +This assignment covers Challenges 10 through 16 plus the 5 bonus challenges. **Both full-workshop and Day-2-only participants accept this assignment.** + +Day-2-only participants will not have completed Assignment 1, but Assignment 2 does not depend on Assignment 1 artifacts. + +Click **New assignment** again and fill in the settings: + + | Setting | Value | + |---|---| + | **Title** | You Can Build This | + | **Type** | Individual | + | **Visibility** | Private | + | **Template repository** | `Community-Access/learning-room-template` | + | **Grant students admin access** | No | + | **Enable feedback pull requests** | Yes | + | **Deadline** | One week after Day 2 (gives students time for the capstone and bonus challenges) | + +Then complete the remaining fields: + +1. **Assignment description:** Use [assignment-day2-you-can-build-this.md](assignment-day2-you-can-build-this.md) +2. **Autograding tests:** Use [autograding-day2.json](autograding-day2.json) +3. Click **Create assignment** -- this generates your Day 2 invite link + +### What the student experiences (Day 2) + +1. Student clicks the Day 2 invite link +2. GitHub Classroom creates a new private repo for Day 2 +3. Facilitator seeds Challenge 10 (Go Local) using `student-progression.yml` +4. Student clones the repo, works locally, pushes, and closes the issue +5. Progression Bot unlocks Challenges 11 through 16 sequentially +6. Challenge 16 (Capstone) has the student fork the accessibility-agents repo and open a cross-fork PR +7. Bonus challenges (A through E) are available via issue templates for students who finish early + +--- + +## Step 5: Share Invite Links + +Each assignment generates a unique invite URL. + +### Where to add the links + +1. Copy the **Day 1 invite URL** from the assignment page +2. In the `git-going-with-github` repository, open `DAY1_AGENDA.md` and replace the `[INVITE_LINK]` placeholder +3. Copy the **Day 2 invite URL** +4. Open `DAY2_AGENDA.md` and replace its `[INVITE_LINK]` placeholder +5. Optionally, email the invite links directly to students before the workshop + +### What students see when they click + +1. GitHub shows a "Join classroom" page if they are not already on the roster +2. If on the roster, they see "Accept this assignment" +3. After accepting, GitHub creates their private repo within 30-60 seconds +4. The student's repository URL follows the pattern: `github.com/Community-Access-Classroom/learning-room-[username]` + +### Which links to send + +| Participant type | Send Day 1 link | Send Day 2 link | +|---|---|---| +| Full workshop (Day 1 + Day 2) | Yes | Yes | +| Day-2-only | No | Yes | + +--- + +## Step 6: Verify Everything Works + +Run this verification with a test account before the workshop. Do not skip this step. + +### Verification checklist + +- [ ] Accept the Day 1 invite with a test GitHub account +- [ ] Verify a student repository was created under the classroom org +- [ ] Verify the learning-room template files are present (`docs/welcome.md`, `docs/keyboard-shortcuts.md`, `docs/setup-guide.md`) +- [ ] Verify Challenge 1 issue was created by the Progression Bot after running `Seed-LearningRoomChallenge.ps1` +- [ ] Open a test PR with a trivial change +- [ ] Verify Aria (PR validation bot) comments within 60 seconds +- [ ] Verify autograding runs and reports a score +- [ ] Verify a feedback pull request was created by Classroom +- [ ] Close Challenge 1 and verify Challenge 2 is created by the Progression Bot +- [ ] Accept the Day 2 invite with the same test account +- [ ] Verify Challenge 10 issue appears in the Day 2 repo +- [ ] Repeat the PR test for the Day 2 repository +- [ ] Delete the test student repositories when done + +### Seeding the first challenge + +After a student accepts the assignment, seed the first challenge from this repository: + +```powershell +scripts/classroom/Seed-LearningRoomChallenge.ps1 -Repository Community-Access-Classroom/learning-room-studentname -Challenge 1 -Assignee studentname +``` + +For 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: + +```powershell +scripts/classroom/Seed-PeerSimulation.ps1 -Repository Community-Access-Classroom/learning-room-studentname -StudentUsername studentname +``` + +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 `docs/welcome.md` on their challenge branch and opened a pull request, run: + +```powershell +scripts/classroom/Start-MergeConflictChallenge.ps1 -Repository Community-Access-Classroom/learning-room-studentname -StudentBranch learn/studentname +``` + +The script changes the same TODO area on `main`, which should cause the student's pull request to report a merge conflict if they edited that TODO on their branch. + +### Autograding verification + +To test specific autograding checks: + +1. In the test student repo, create a branch and make a change that should pass a check +2. Open a PR +3. Go to the **Actions** tab and verify the autograding workflow ran +4. Check the workflow output -- each test should report pass or fail correctly +5. Try a change that should fail a check and verify it catches the problem + +### Aria verification + +1. Open a PR without a `Closes #XX` reference +2. Verify Aria posts a comment asking for an issue link +3. Comment `@aria-bot I have a merge conflict, can you explain this?` +4. Verify the comment responder replies with guidance + +--- + +## Step 7: Day-of-Workshop Facilitation + +### Before students arrive + +- [ ] Verify the classroom dashboard loads at [classroom.github.com](https://classroom.github.com) +- [ ] Have both invite links ready to share (on-screen, in chat, or printed on cards) +- [ ] Open the [grading-guide.md](grading-guide.md) for reference during the day +- [ ] Have the [Challenge Hub](../docs/CHALLENGES.md) open in a browser tab + +### During the workshop + +**Monitor the classroom dashboard:** It shows accepted assignments, recent commits, and autograding results in real time. + +**Common student issues and fixes:** + +| Issue | What to Do | +|---|---| +| "I cannot find the invite link" | Reshare the link; post it in the workshop chat channel | +| "My next challenge did not appear" | The student may not have closed the previous issue; check their Issues tab | +| "Autograding says I failed" | Check the workflow output; often a formatting issue; use it as a teaching moment | +| "I do not see the feedback PR" | It appears after the first push; have them make any commit and push | +| "Aria did not comment on my PR" | Check the Actions tab in the student repo; workflows may need to be enabled | +| "Assignment not showing my work" | Student may have pushed to the wrong branch; check their repo's branches | + +### Using the feedback PR + +The feedback pull request is Classroom's built-in channel for async facilitator comments: + +1. Open a student's repository from the classroom dashboard +2. Go to the **Pull Requests** tab +3. Open the feedback PR (titled "Feedback") +4. Leave comments, encouragement, and guidance here +5. Students receive email notifications for your comments + +--- + +## How Challenges Flow Through the System + +### Challenge progression + +The Student Progression Bot manages the entire challenge sequence. Each student works through challenges independently in their own repo: + +#### Day 1 (Assignment 1): Challenges 1-9 + +| Challenge | Title | How it completes | Aria validates | Autograded | +|---|---|---|---|---| +| 1 | Find Your Way Around | Close issue | -- | -- | +| 2 | File Your First Issue | Close issue | -- | -- | +| 3 | Join the Conversation | Close issue | -- | -- | +| 4 | Branch Out | Close issue | -- | Yes (branch exists) | +| 5 | Make Your Mark | Close issue | -- | Yes (file edited) | +| 6 | Open Your First Pull Request | Close issue | Yes (PR structure) | Yes (issue reference) | +| 7 | Survive a Merge Conflict | Close issue | Yes (PR feedback) | Yes (no conflict markers) | +| 8 | The Culture Layer | Close issue | -- | -- | +| 9 | Merge Day | Close issue | Yes (merge) | Yes (PR merged) | + +#### Day 2 (Assignment 2): Challenges 10-16 + Bonus + +| Challenge | Title | How it completes | Aria validates | Autograded | +|---|---|---|---|---| +| 10 | Go Local | Close issue | -- | Yes (local commit) | +| 11 | Open a Day 2 PR | Close issue | Yes (PR structure) | Yes (local push) | +| 12 | Review Like a Pro | Close issue | -- | Yes (review comment) | +| 13 | AI as Your Copilot | Close issue | -- | -- | +| 14 | Template Remix | Close issue | -- | Yes (YAML valid) | +| 15 | Meet the Agents | Close issue | -- | -- | +| 16 | Build Your Agent (Capstone) | Close issue | -- | Yes (agent file) | +| A-E | Bonus challenges | Close issue | -- | -- | + +### Challenges that cannot be automated + +Challenges 1, 2, 3, 8, 13, and 15 are evaluated manually using the [grading-guide.md](grading-guide.md). The Progression Bot still unlocks the next challenge when the student closes the issue -- the facilitator reviews evidence in the issue comments. + +--- + +## Post-Workshop + +Follow the [teardown-checklist.md](teardown-checklist.md) for complete post-workshop steps. The key actions: + +1. **Export grades** from the classroom dashboard +2. **Archive the classroom** in the Classroom UI (this preserves student repos as read-only portfolio pieces) +3. **Review feedback** and update facilitation notes for next cohort + +--- + +## Customization Options + +### Adjusting deadlines + +Edit the assignment deadline in the Classroom UI at any time. Students who already accepted will see the updated deadline. + +### Adding or removing autograding tests + +Modify tests in the Classroom UI: + +1. Open the assignment +2. Scroll to **Autograding** +3. Add, edit, or remove individual tests +4. Changes apply to all future student pushes (not retroactively) + +### Changing point values + +The point values in the JSON files are suggestions. Adjust them in the Classroom UI to match your grading approach. The [grading-guide.md](grading-guide.md) has recommended completion thresholds. + +### Disabling autograding + +If you prefer manual-only grading, skip adding the autograding tests when creating the assignment. Aria and the Progression Bot still work independently of autograding. + +--- + +## Legacy Notes + +Previous versions of this workshop used a shared "multi-player sandbox" repository model where a facilitator manually provisioned challenge issues for each student using PowerShell scripts (`create_all_challenges.ps1` and `create_student_issues.ps1`). That approach required: + +- Creating a per-cohort `learning-room-[cohort]` repository from the template +- Inviting all students to the GitHub organization +- Running batch scripts to create challenge issues per student via the GitHub API (the scripts split chapters into sub-challenges like 04.1, 04.2, 04.3, totaling 26 issues per student) +- Updating curriculum links with find-and-replace across all Markdown files + +The current model replaces all of that with GitHub Classroom. Each student gets their own private repo automatically when they accept the invite link, and the Student Progression Bot handles challenge delivery. The legacy scripts are preserved in the repository's Git history for reference but are no longer needed for deployment. + +Key decisions preserved from the legacy scripts: + +- The scripts defined 26 sub-challenges across chapters 4-16, which the current system consolidates into 16 core challenges + 5 bonus challenges (21 total) +- Challenges used two submission types: issue comment (evidence-based) and PR with `Closes #XX` (code-based) +- The script was idempotent -- safe to rerun for late-joining students +- Labels followed the pattern: `challenge`, `challenge: [level]`, `skill: [tag]`, `day: [1 or 2]` + +## After the Workshop + +See [teardown-checklist.md](teardown-checklist.md) for the complete post-workshop cleanup process, including: + +- Exporting grades from the classroom dashboard +- Archiving the classroom +- Cleaning up student repositories +- Documenting facilitator notes for the next cohort + +## Reference Links + +- [GitHub Classroom documentation](https://docs.github.com/en/education/manage-coursework-with-github-classroom) +- [Autograding documentation](https://docs.github.com/en/education/manage-coursework-with-github-classroom/teach-with-github-classroom/use-autograding) +- [Facilitator Guide](../facilitator/FACILITATOR_GUIDE.md) -- workshop-level facilitation reference +- [Challenge Hub](../docs/CHALLENGES.md) -- all 21 challenges with instructions +- [Solutions Directory](../docs/solutions/) -- reference solutions for facilitator use +- [Grading Guide](grading-guide.md) -- per-challenge rubric and completion levels diff --git a/admin/qa-bundle/classroom/assignment-day1-you-belong-here.md b/admin/qa-bundle/classroom/assignment-day1-you-belong-here.md new file mode 100644 index 0000000..b8f9710 --- /dev/null +++ b/admin/qa-bundle/classroom/assignment-day1-you-belong-here.md @@ -0,0 +1,82 @@ + + +# Assignment 1: You Belong Here + +Welcome to Git Going with GitHub! This is your private learning repository for Day 1. Everything you do here is yours -- experiment freely. + +## What You Will Do Today + +During the live Day 1 core path, you will practice the skills needed to make your first browser-based GitHub contribution. If the room needs more time, later challenges can continue during open lab time or after the event. + +- Navigate a real GitHub repository using your screen reader +- File your first issue describing something you noticed +- Communicate with teammates using @mentions and comments +- Create a branch to work in safely +- Make your first commit to a file +- Open a pull request linking your work to an issue +- Learn how merge conflicts work, with live support if time allows +- Reflect on open source culture and communication, live or asynchronously +- Merge a pull request into the main branch, or leave with clear next steps to finish it + +## Challenges + +Complete these challenges in order. Each one builds on the previous. When you close a challenge issue, the Student Progression Bot automatically opens your next challenge. The live agenda prioritizes Challenges 1-6; Challenges 7-9 are available as stretch or async follow-up. + +| Challenge | What You Do | Chapter | +|---|---|---| +| 1. Find Your Way Around | Explore the repository structure and locate key files | [Chapter 3](https://github.com/Community-Access/git-going-with-github/blob/main/docs/03-navigating-repositories.md) | +| 2. File Your First Issue | Create an issue describing something you noticed | [Chapter 5](https://github.com/Community-Access/git-going-with-github/blob/main/docs/05-working-with-issues.md) | +| 3. Join the Conversation | Mention a teammate or bot using @mentions | [Chapter 5](https://github.com/Community-Access/git-going-with-github/blob/main/docs/05-working-with-issues.md) | +| 4. Branch Out | Create a feature branch for your work | [Chapter 4](https://github.com/Community-Access/git-going-with-github/blob/main/docs/04-the-learning-room.md) | +| 5. Make Your Mark | Edit a file and commit with a clear message | [Chapter 4](https://github.com/Community-Access/git-going-with-github/blob/main/docs/04-the-learning-room.md) | +| 6. Open Your First Pull Request | Open a PR that references an issue with `Closes #N` | [Chapter 6](https://github.com/Community-Access/git-going-with-github/blob/main/docs/06-working-with-pull-requests.md) | +| 7. Survive a Merge Conflict | Understand and fix conflict markers | [Chapter 7](https://github.com/Community-Access/git-going-with-github/blob/main/docs/07-merge-conflicts.md) | +| 8. The Culture Layer | Reflect on community norms and communication | [Chapter 8](https://github.com/Community-Access/git-going-with-github/blob/main/docs/08-open-source-culture.md) | +| 9. Merge Day | Get your PR reviewed, approved, and merged | [Chapter 10](https://github.com/Community-Access/git-going-with-github/blob/main/docs/10-notifications-and-day-1-close.md) | + +## Autograded Challenges + +Challenges 2, 5, 6, and 7 have automated checks that run when you push or open a PR: + +- **Challenge 2:** Verifies you have filed at least one issue +- **Challenge 5:** Verifies at least one commit exists on a non-default branch +- **Challenge 6:** Verifies your PR body contains `Closes`, `Fixes`, or `Resolves` +- **Challenge 7:** Verifies no merge conflict markers remain in `docs/` + +The autograder posts feedback as a PR comment. If a check fails, read the feedback and push an update. + +## Evidence + +Each challenge has an issue that the Student Progression Bot creates for you. Complete the challenge, leave a comment with your evidence, and close the issue to unlock the next one. + +## If You Get Stuck + +Every chapter has an "If You Get Stuck" section with specific troubleshooting steps. Start there. + +You can also: +- Ask your assigned buddy or study group +- Post a question on the issue thread +- Mention `@aria-bot` in a comment for a workspace check +- Ask a facilitator for help -- that is what they are here for + +## After Day 1 + +When you complete all 9 challenges, you have the foundation for everything in Day 2 -- or for contributing to any open source project on your own. These skills are yours permanently. + +**Continuing to Day 2?** See the [Day 2 assignment](https://github.com/Community-Access/git-going-with-github/blob/main/classroom/assignment-day2-you-can-build-this.md) for what comes next. + +**Day 1 is your only day?** Everything you learned today is complete and self-contained. See the [Next Steps guide](https://github.com/Community-Access/git-going-with-github/blob/main/docs/21-next-steps.md) for how to continue your GitHub journey independently. + +## Bonus Challenges + +If you finish early, check the [Challenges page](https://github.com/Community-Access/git-going-with-github/blob/main/docs/CHALLENGES.md) for bonus challenges A through E. diff --git a/admin/qa-bundle/classroom/assignment-day2-you-can-build-this.md b/admin/qa-bundle/classroom/assignment-day2-you-can-build-this.md new file mode 100644 index 0000000..3252487 --- /dev/null +++ b/admin/qa-bundle/classroom/assignment-day2-you-can-build-this.md @@ -0,0 +1,83 @@ + + +# Assignment 2: You Can Build This + +Welcome back -- or welcome for the first time! Day 2 moves from the browser to your local machine and introduces real-world development workflows. + +## Joining Day 2 Without Day 1? + +You do not need to have attended Day 1 to succeed today. If you already have GitHub fundamentals (navigating repos, filing issues, opening PRs, reviewing code), you have the same foundation as Day 1 participants. + +Before starting the challenges below, verify your readiness with the [Day 2 Quick Start](https://github.com/Community-Access/git-going-with-github/blob/main/admin/DAY2_QUICK_START.md) guide. It takes about 30 minutes and confirms you have the accounts, tools, and skills needed. + +## What You Will Do Today + +During the live Day 2 core path, you will move from browser-based GitHub to local contribution work in VS Code. Some advanced challenges are intentionally available as stretch or async follow-up so participants and remote cohorts can continue at a sustainable pace. + +- Clone a repository and work with Git locally +- Push a branch and open a PR from your local machine +- Review a classmate's code and give constructive feedback +- Use GitHub Copilot as a collaborative tool +- Create or review a custom issue template, if time allows +- Fork a real repository and prepare a cross-repo contribution path +- Explore accessibility agents and how they work +- Start your own agent or capstone idea, with a path to finish asynchronously + +## Challenges + +Complete these challenges in order. Each one builds on the previous. The live agenda prioritizes Challenges 10-13 and agent discovery; Challenges 14-16 can be completed during lab time or after the event. + +| Challenge | What You Do | Chapter | +|---|---|---| +| 10. Go Local | Clone, branch, edit, commit, and push using local Git | [Chapter 14](https://github.com/Community-Access/git-going-with-github/blob/main/docs/14-git-in-practice.md) | +| 11. Open a Day 2 PR | Open a PR from your locally-pushed branch | [Chapter 15](https://github.com/Community-Access/git-going-with-github/blob/main/docs/15-code-review.md) | +| 12. Review Like a Pro | Review a classmate's PR with specific, constructive feedback | [Chapter 15](https://github.com/Community-Access/git-going-with-github/blob/main/docs/15-code-review.md) | +| 13. AI as Your Copilot | Use Copilot to improve documentation and evaluate its output | [Chapter 16](https://github.com/Community-Access/git-going-with-github/blob/main/docs/16-github-copilot.md) | +| 14. Template Remix | Create a custom YAML issue template | [Chapter 17](https://github.com/Community-Access/git-going-with-github/blob/main/docs/17-issue-templates.md) | +| 15. Meet the Agents | Explore and run agents from the accessibility-agents repo | [Chapter 19](https://github.com/Community-Access/git-going-with-github/blob/main/docs/19-accessibility-agents.md) | +| 16. Build Your Agent (Capstone) | Design and submit an original agent with responsibilities and guardrails | [Chapter 20](https://github.com/Community-Access/git-going-with-github/blob/main/docs/20-build-your-agent.md) | + +## Autograded Challenges + +Challenges 10, 14, and 16 have automated checks that run when you open a PR: + +- **Challenge 10:** Verifies at least one commit exists on a non-default branch +- **Challenge 14:** Verifies your YAML template has required `name` and `description` fields +- **Challenge 16:** Verifies your agent file has valid frontmatter, responsibilities, and guardrails + +The autograder posts feedback as a PR comment. If a check fails, read the feedback and push an update. + +## Evidence + +Each challenge has an issue template in the Learning Room. Open the matching issue, complete the challenge, and post your evidence as described in the issue. Challenges 10, 14, and 16 also have automated checks that post PR feedback when you push or open a pull request; use those bot comments as guidance, then keep your human evidence in the challenge issue. + +## If You Get Stuck + +Every chapter has an "If You Get Stuck" section with specific troubleshooting steps. Start there. + +The [solutions directory](https://github.com/Community-Access/git-going-with-github/tree/main/docs/solutions) has reference solutions for every challenge. These show annotated examples of what a completed challenge looks like. + +## Fork Workflow (Challenges 15-16) + +For the capstone challenges, you will work with the [accessibility-agents](https://github.com/Community-Access/accessibility-agents) repository: + +1. Fork the repository to your account +2. Clone your fork locally +3. Create a branch for your work +4. Open a PR from your fork back to the original + +See [Chapter 18](https://github.com/Community-Access/git-going-with-github/blob/main/docs/18-fork-and-contribute.md) for the full fork workflow. If forking is new to you, [Chapter 6: Working with Pull Requests](https://github.com/Community-Access/git-going-with-github/blob/main/docs/06-working-with-pull-requests.md) covers the fundamentals. + +## Bonus Challenges + +If you finish early, check the [Challenges page](https://github.com/Community-Access/git-going-with-github/blob/main/docs/CHALLENGES.md) for bonus challenges. diff --git a/admin/qa-bundle/classroom/autograding-day1.json b/admin/qa-bundle/classroom/autograding-day1.json new file mode 100644 index 0000000..5c5fa77 --- /dev/null +++ b/admin/qa-bundle/classroom/autograding-day1.json @@ -0,0 +1,42 @@ +[ + { + "test_name": "Challenge 2: Issue Filed", + "setup": "", + "run": "gh issue list --repo $GITHUB_REPOSITORY --author $GITHUB_ACTOR --state all --json number --jq 'length' | xargs test 0 -lt", + "input": "", + "expected_output": "", + "comparison": "exact", + "timeout": 10, + "points": 10 + }, + { + "test_name": "Challenge 5: Commit Exists", + "setup": "", + "run": "git log --oneline --all --author=$GITHUB_ACTOR | head -1 | grep -q '.'", + "input": "", + "expected_output": "", + "comparison": "exact", + "timeout": 10, + "points": 10 + }, + { + "test_name": "Challenge 6: PR with Issue Link", + "setup": "", + "run": "gh pr list --repo $GITHUB_REPOSITORY --author $GITHUB_ACTOR --state all --json body --jq '.[0].body' | grep -iq 'closes\\|fixes\\|resolves'", + "input": "", + "expected_output": "", + "comparison": "exact", + "timeout": 10, + "points": 15 + }, + { + "test_name": "Challenge 7: No Conflict Markers", + "setup": "", + "run": "! grep -rn '<<<<<<< \\|======= \\|>>>>>>> ' docs/ 2>/dev/null", + "input": "", + "expected_output": "", + "comparison": "exact", + "timeout": 10, + "points": 15 + } +] diff --git a/admin/qa-bundle/classroom/autograding-day2.json b/admin/qa-bundle/classroom/autograding-day2.json new file mode 100644 index 0000000..ac6d3b5 --- /dev/null +++ b/admin/qa-bundle/classroom/autograding-day2.json @@ -0,0 +1,62 @@ +[ + { + "test_name": "Challenge 10: Go Local - Commit on Branch", + "setup": "", + "run": "git log --oneline origin/main..HEAD 2>/dev/null | head -1 | grep -q '.' || git branch -r --list 'origin/*' | grep -v main | head -1 | xargs -I{} git log --oneline origin/main..{} | head -1 | grep -q '.'", + "input": "", + "expected_output": "", + "comparison": "exact", + "timeout": 10, + "points": 15 + }, + { + "test_name": "Challenge 14: Template Remix - Custom Issue Template Exists", + "setup": "", + "run": "find .github/ISSUE_TEMPLATE -name '*.yml' ! -name 'challenge-*.yml' ! -name 'bonus-*.yml' ! -name 'config.yml' 2>/dev/null | head -1 | grep -q '.'", + "input": "", + "expected_output": "", + "comparison": "exact", + "timeout": 10, + "points": 15 + }, + { + "test_name": "Challenge 14: Template Remix - Template Has Required Fields", + "setup": "", + "run": "TEMPLATE=$(find .github/ISSUE_TEMPLATE -name '*.yml' ! -name 'challenge-*.yml' ! -name 'bonus-*.yml' ! -name 'config.yml' 2>/dev/null | head -1); grep -q '^name:' \"$TEMPLATE\" && grep -q '^description:' \"$TEMPLATE\"", + "input": "", + "expected_output": "", + "comparison": "exact", + "timeout": 10, + "points": 10 + }, + { + "test_name": "Challenge 16: Build Your Agent - Agent File Exists", + "setup": "", + "run": "find agents community-agents -name '*.md' 2>/dev/null | head -1 | grep -q '.'", + "input": "", + "expected_output": "", + "comparison": "exact", + "timeout": 10, + "points": 10 + }, + { + "test_name": "Challenge 16: Build Your Agent - Agent Has Frontmatter", + "setup": "", + "run": "AGENT=$(find agents community-agents -name '*.md' 2>/dev/null | head -1); head -1 \"$AGENT\" | grep -q '^---'", + "input": "", + "expected_output": "", + "comparison": "exact", + "timeout": 10, + "points": 10 + }, + { + "test_name": "Challenge 16: Build Your Agent - Agent Has Responsibilities and Guardrails", + "setup": "", + "run": "AGENT=$(find agents community-agents -name '*.md' 2>/dev/null | head -1); grep -qi '## responsibilities\\|## what this agent does' \"$AGENT\" && grep -qi '## guardrails\\|## limitations\\|## boundaries' \"$AGENT\"", + "input": "", + "expected_output": "", + "comparison": "exact", + "timeout": 10, + "points": 15 + } +] diff --git a/admin/qa-bundle/classroom/grading-guide.md b/admin/qa-bundle/classroom/grading-guide.md new file mode 100644 index 0000000..a133550 --- /dev/null +++ b/admin/qa-bundle/classroom/grading-guide.md @@ -0,0 +1,86 @@ +# 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 + +The autograding JSON files define automated tests that run on student PRs. These 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 [autograding-day1.json](autograding-day1.json) and [autograding-day2.json](autograding-day2.json)): + +- 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 the autograder will post pass/fail results as a 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 (auto) | Agent file with PR to accessibility-agents, plus peer-simulation or real peer review evidence | Has frontmatter, responsibilities, guardrails | + +### 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 initiative. +- **Student joined on Day 2 without attending Day 1:** Evaluate on Day 2 challenges only. They verified their GitHub fundamentals via the Day 2 Quick Start self-assessment. Do not require Day 1 challenge completion. diff --git a/admin/qa-bundle/classroom/roster-template.csv b/admin/qa-bundle/classroom/roster-template.csv new file mode 100644 index 0000000..a108b8d --- /dev/null +++ b/admin/qa-bundle/classroom/roster-template.csv @@ -0,0 +1,7 @@ +identifier,name,email +# GitHub username,Full name (optional),Email (optional) +# Fill in students' GitHub usernames before importing into GitHub Classroom +# Minimum required: identifier column with GitHub usernames +# Example: +# maria-student,Maria Garcia,maria@example.com +# alex-student,Alex Chen, diff --git a/admin/qa-bundle/docs/00-pre-workshop-setup.md b/admin/qa-bundle/docs/00-pre-workshop-setup.md new file mode 100644 index 0000000..8fc1b56 --- /dev/null +++ b/admin/qa-bundle/docs/00-pre-workshop-setup.md @@ -0,0 +1,986 @@ +# Pre-Workshop Setup - GIT Going with GitHub +> +> **Listen to Episode 1:** [Pre-Workshop Setup](../admin/PODCASTS.md) - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. + +> **Related appendices:** [Appendix D: Git Authentication](appendix-d-git-authentication.md) | [Appendix Y: Workshop Materials](appendix-y-workshop-materials.md) | [Appendix Z: GitHub Skills](appendix-z-github-skills.md) +> **Authoritative sources:** [GitHub Docs: Create an account](https://docs.github.com/en/get-started/start-your-journey/creating-an-account-on-github) | [GitHub Docs: Set up Git](https://docs.github.com/en/get-started/getting-started-with-git/set-up-git) + + +## Everything You Need Before Day 1 Begins + +> **A [Community Access](https://community-access.org) workshop.** +> +> **Please complete this guide at least one day before the workshop.** If you run into any issues, [file an issue](https://github.com/community-access/git-going-with-github/issues) so we can help - we want Day 1 to start with everyone ready to go, not troubleshooting. + +If you want the most guided starting path, begin with [Get Going with GitHub](get-going.md). It explains how GitHub Classroom, your Learning Room repository, Challenge 1, evidence prompts, and tool choice all fit together before you start setup. + +## Table of Contents + +1. [What You Will Need](#what-you-will-need) +2. [Step 1 - Create Your GitHub Account](#step-1---create-your-github-account) +3. [Step 2 - Configure GitHub Accessibility Settings](#step-2---configure-github-accessibility-settings) +4. [Step 3 - Configure Your Profile](#step-3---configure-your-profile) +5. [Step 4 - Check GitHub Feature Preview Settings](#step-4---check-github-feature-preview-settings) +6. [Step 5 - Set Up Your Screen Reader and Browser](#step-5---set-up-your-screen-reader--browser) +7. [Step 6 - Install Git and Visual Studio Code](#step-6---install-git-and-visual-studio-code) +8. [Step 7 - Configure Git Identity](#step-7---configure-git-identity) +9. [Step 8 - Install VS Code Extensions](#step-8---install-vs-code-extensions) +10. [Step 9 - Verification Checklist](#step-9---verification-checklist) +11. [Other GitHub Access Methods (Reference Only)](#other-github-access-methods-reference-only) +12. [Getting Help Before the Event](#getting-help-before-the-event) + +## What You Will Need + +### Hardware + +- A computer running Windows or macOS +- A reliable internet connection +- Headphones (recommended - screen reader audio during group sessions) + +### Software - Day 1 + +- A modern web browser: **Chrome** or **Firefox** recommended + - Both have strong compatibility with GitHub's interface and screen readers + - Edge is also acceptable on Windows + - Safari is the recommended browser on macOS with VoiceOver +- A screen reader (see options below) +- A GitHub account (free tier is fine) + +### Software - Required Before the Workshop + +- **Git** - [Download Git](https://git-scm.com/downloads) (Windows/Linux) or Xcode Command Line Tools (macOS) +- **Visual Studio Code** (free) - [download here](https://code.visualstudio.com/) (GitHub Copilot is included automatically) +- A GitHub Copilot subscription or Free tier access (Copilot Free is available to all GitHub users) + +### Screen Reader Options + +You only need **one** of these. Use whichever you are most comfortable with. + +| Screen Reader | Platform | Cost | Download | +| --------------- | ---------- | ------ | ---------- | +| **NVDA** (NonVisual Desktop Access) | Windows | Free | [Download NVDA](https://www.nvaccess.org/download/) | +| **JAWS** (Job Access With Speech) | Windows | Paid (trial available) | [Download JAWS](https://www.freedomscientific.com/products/software/jaws/) | +| **VoiceOver** | macOS / iOS | Built-in (free) | Included with macOS - press `Cmd+F5` to activate | + +> **Note:** All workshop exercises are designed to work with any of these screen readers. Where specific key commands differ, we will note all three. You are not disadvantaged by using any particular screen reader. + + +## Step 1 - Create Your GitHub Account + +> **See also:** [Appendix D: Git Authentication](appendix-d-git-authentication.md) covers SSH keys and personal access tokens in detail. + +If you already have a GitHub account, skip to [Step 2](#step-2---configure-github-accessibility-settings). + +> **Before you begin:** Have your email address and a chosen password ready. The signup form is a single-page form with several fields - your screen reader will encounter a verification puzzle partway through (see note below). + +### Create an account + +1. Open your browser and navigate to the **[GitHub signup page](https://github.com/signup)** +2. The page loads with focus on the first field: **"Enter your email address"** + - Type your email address and press `Tab` or activate **Continue** +3. The next field is **"Create a password"** + - Choose a password of at least 8 characters (15+ recommended). Press `Tab` or **Continue** +4. The next field is **"Enter a username"** + - Your username appears on every issue, PR, and comment you make. Guidelines: + - Use lowercase letters, numbers, and hyphens only + - Keep it professional - it represents you in the open source community + - GitHub will tell you immediately if the name is taken + - Press `Tab` or **Continue** +5. The next question asks whether you want to receive product updates by email + - Press `Tab` to reach the **"y"** or **"n"** options and press `Enter`, or type `y` or `n` directly +6. **Human verification step** + +
+ Visual / mouse users + + GitHub presents a visual CAPTCHA puzzle to verify you are human. Follow the on-screen prompts - typically clicking images that match a category, or checking a box. If the puzzle does not load, try refreshing the page. + +
+ +
+ Screen reader users + + GitHub's visual CAPTCHA is a known accessibility barrier. After the CAPTCHA appears: + - Look for a button or link labeled **"Audio"** or **"Try an audio challenge"** - an audio CAPTCHA alternative may be available + - If no audio option appears, or if neither challenge is accessible, contact the workshop organizer before the event - they can assist with account verification + - If you complete an audio challenge, you will hear words or digits to type into a text field + +
+ +7. Activate the **Create account** button +8. GitHub sends a **launch code** (a short numeric code) to your email inbox + - Check your email, copy the code, return to the browser, and type it into the verification field + - If you don't receive it within a few minutes, check your spam folder +9. You will land on a "Welcome to GitHub" personalization page - you can skip it or answer the questions; it does not affect your account functionality + +### Verify your email address + +GitHub also sends a **separate** email verification link after account creation. Check your inbox for an email from GitHub with subject "Please verify your email address" and activate the link inside it. Some GitHub features (including creating repositories) require a verified email. + +### Enable two-factor authentication (2FA): detailed guidance and workshop policy + +Two-factor authentication (2FA) adds a second verification step each time you sign in, protecting your account if your password is compromised. GitHub now requires 2FA for all accounts, so you may already have it enabled. If not, set it up now. We recommend using the **GitHub Mobile app** for the smoothest experience - see the options below. + +### Quick steps to enable 2FA + +1. Open the [GitHub security settings page](https://github.com/settings/security) while signed in. +2. Under **Two-factor authentication**, choose **Enable** and follow the prompts. +3. Choose one of the second-factor methods (recommended order): + - **GitHub Mobile app** (recommended for this workshop): Install the free [GitHub Mobile](https://github.com/mobile) app on your phone. Once linked to your account, GitHub sends a push notification to your phone each time you sign in. You simply tap **Approve** - no codes to type. The app is available for iOS and Android and supports VoiceOver and TalkBack. + - **Authenticator app**: Microsoft Authenticator, Google Authenticator, Authy - generates time-based 6-digit codes. + - **Security key / passkey** (most secure): hardware security keys (YubiKey, etc.) or platform passkeys (biometric device credentials). + - **SMS / text message** (least preferred): can be used if other options are unavailable. + +### Detailed setup notes + +- Authenticator app (recommended): + - Visual users: scan the QR code with your authenticator app and enter the 6-digit code shown. + - Screen reader users: choose the link labeled **"enter this text code"** or **"can't scan the barcode?"** to reveal the secret (a 32-character key). Use the authenticator app's manual/key-entry option to add the account. + +- Security key / passkey: + - Follow the on-screen prompts to register a hardware key or platform passkey. These are highly recommended for long-term security and are supported by modern browsers and devices. + +- SMS / text message: + - Enter your phone number and verify the code sent via text. Use only if authenticator apps or keys are unavailable. + +### Recovery and backup + +- After enabling 2FA, GitHub will display **recovery (single-use) codes**. Immediately copy, download, or securely store these codes (password manager or physically secure location). They are the only fallback if you lose your second-factor device. +- Consider registering more than one second-factor method (e.g., authenticator app + a hardware key) to avoid account lockout. + +### Authenticating Git with GitHub: browser-based sign-in (OAuth) + +When you use Git inside VS Code or GitHub Desktop, you do not need to manage passwords, tokens, or SSH keys manually. These tools use **browser-based OAuth sign-in** - the same "Sign in with GitHub" flow you use on any website: + +1. The first time you push or pull code, VS Code (or GitHub Desktop) opens your default web browser to a GitHub authorization page. +2. Sign in to GitHub in the browser (including your 2FA step - a push notification if you use GitHub Mobile, or a code from your authenticator app). +3. Approve the authorization request. +4. Switch back to VS Code. Your credentials are securely stored by your operating system's credential manager, so you will not be prompted again on this machine. + +That is it. No tokens to generate, no keys to create, no strings to paste. If you are using GitHub Mobile for 2FA, the entire flow is: type your password, tap **Approve** on your phone, and you are authenticated. + +> **Screen reader note:** The authorization page opens in your default browser. After approving, the browser shows a message saying you can return to VS Code. Use `Alt+Tab` (Windows) or `Cmd+Tab` (macOS) to switch back. + +> **Default browser warning:** VS Code opens the GitHub authorization page in your operating system's **default browser**, not necessarily the browser you use day-to-day. If your default browser is set to something unexpected (for example, an older browser without your screen reader configured), the OAuth page may open in an unfamiliar environment. +> +> **Before the workshop:** Verify which browser is your OS default: +> - **Windows:** Settings, Apps, Default apps, look for "Web browser" +> - **macOS:** System Settings, Desktop and Dock, Default web browser +> +> Set it to the browser where your screen reader and GitHub login are already configured. This avoids a confusing moment during the first `git push` when the authorization page opens somewhere you did not expect. + +> **Tip - GitHub Mobile for push notification 2FA:** If you have not already, install the free [GitHub Mobile](https://github.com/mobile) app (iOS and Android). Once linked to your account, every 2FA prompt becomes a single tap on a push notification instead of typing a 6-digit code. The app supports VoiceOver (iOS) and TalkBack (Android). + +### Workshop policy + +For this workshop, participants need a GitHub account with 2FA enabled. The browser-based sign-in described above handles all Git authentication automatically - no additional setup is required beyond having a working GitHub account. + +If you run into any authentication issues before the workshop, contact the workshop organizers at the email or issue link in this guide so we can help. + +### Learning Cards: Create Your GitHub Account + +
+Screen reader users + +- During signup, press `Tab` to move between form fields; GitHub announces validation errors inline as you type +- The CAPTCHA step may not have an audio fallback -- look for a button labeled "Audio" or "Try an audio challenge" before requesting help +- After enabling 2FA, use `Ctrl+A` then `Ctrl+C` in the recovery codes text area to copy all codes at once into a password manager + +
+ +
+Low vision users + +- GitHub signup fields have high-contrast focus rings; if you cannot see them, switch to your browser's High Contrast mode (`Alt+Shift+H` in Edge) before starting +- Zoom to 200% on the verification puzzle -- the puzzle images scale but button text may overlap; resize the browser window wider if controls disappear +- Recovery codes are displayed in small monospace text; use `Ctrl+Plus` to enlarge before copying them + +
+ +
+Sighted users + +- Watch for the green checkmark next to the username field confirming your chosen name is available +- The verification email sometimes lands in spam -- check your Junk folder if nothing arrives within two minutes +- After enabling 2FA, the recovery codes appear in a grey box below the QR code; screenshot or download them immediately + +
+ + +## Step 2 - Configure GitHub Accessibility Settings + +These settings make GitHub significantly more usable with a screen reader. **Do not skip this section** - one setting in particular (hovercards) adds significant noise to every page if left on. + +### Navigate to Accessibility Settings + +The fastest path for everyone: navigate directly to **[GitHub Accessibility Settings](https://github.com/settings/accessibility)** while signed in. + +If you prefer to navigate through the interface: + +
+Visual / mouse users + +1. Click your **profile picture** (avatar) in the top-right corner of any GitHub page +2. A dropdown menu appears - click **Settings** +3. On the Settings page, scroll the **left sidebar** and click **Accessibility** + +
+ +
+Screen reader users (NVDA / JAWS) + +1. On any GitHub page, switch to Browse Mode if you are not already in it (`NVDA+Space` / JAWS virtual cursor should be on by default in browsers) +2. Press `B` repeatedly until you hear **"Open user navigation menu, button"** (top-right of the page) and press `Enter` +3. Navigate the menu with `↓` or `K` until you hear **"Settings"** and press `Enter` +4. On the Settings page, press `D` to move through landmark regions until you reach the left sidebar navigation +5. Press `K` or `↓` to navigate through sidebar links until you hear **"Accessibility"** and press `Enter` + +
+ +
+Screen reader users (VoiceOver on macOS) + +1. Press `VO+U` to open the Rotor, arrow to Buttons, find **"Open user navigation menu"** and press `Enter` +2. Press `VO+Down Arrow` to find **"Settings"** and press `VO+Space` +3. On Settings, press `VO+U`, go to Links, find **"Accessibility"** and press `Enter` + +
+ +### Settings to configure + +Work through each setting below. All are on the [Accessibility settings page](https://github.com/settings/accessibility) unless noted. + +#### 1. Disable Hovercards (highest priority) + +> **Do this first.** Hovercards are the most disruptive default setting for screen reader users on GitHub. When enabled, every link announces its hover keyboard shortcut (`H`) as you navigate past it, dramatically slowing page reading. + +
+Visual / mouse users + +On the Accessibility settings page, look for a checkbox or toggle labeled **"Link previews"** or **"Hovercards"**. If it is turned on, click it to turn it off. The change saves automatically. + +
+ +
+Screen reader users + +1. On the Accessibility settings page, switch to Browse Mode if not already active +2. Press `F` or `X` to jump through form controls until you hear **"Link previews"** or **"Hovercards"** +3. If it is announced as **checked** or **on**, press `Space` to turn it off +4. The change saves automatically - no Submit button required + +
+ +#### 2. Enable Link Underlines + +
+Visual / mouse users + +Find the **Link underlines** checkbox or toggle and turn it on. This adds underlines to all links on GitHub, making them distinguishable without relying on colour alone. + +
+ +
+Screen reader users + +1. Press `F` or `X` to navigate form controls until you hear **"Link underlines"** +2. If it is announced as **unchecked**, press `Space` to enable it +3. The change saves automatically + +
+ +#### 3. Character Key Shortcuts + +1. Find **"Character key shortcuts"** +2. Single-key shortcuts (`H` for next heading, `I` for next issue, etc.) speed up navigation but **can conflict with screen reader quick-navigation keys** + - If your screen reader uses letters for navigation in Browse Mode (NVDA, JAWS), GitHub's single-key shortcuts are suppressed when Browse Mode is active, so conflicts are rare in practice + - If you notice unexpected behavior, return here and turn them off +3. Leave at the default unless you have a reason to change it + +#### 4. Set Your Theme (Appearance Settings) + +Theme is on a separate page: [GitHub Appearance Settings](https://github.com/settings/appearance) + +1. Navigate to that page +2. Find the **"Theme mode"** or **"Theme"** section +3. Options available: + - **Light default** - standard white background + - **Dark default** - dark background, easier on some eyes + - **High contrast light** - maximum contrast, recommended for low vision + - **High contrast dark** - maximum contrast on dark background + - **Colorblind** variants - Protanopia, Deuteranopia, Tritanopia +4. Select your preferred theme and activate **Save** if prompted (some changes apply immediately) + +### Learning Cards: Configure GitHub Accessibility Settings + +
+Screen reader users + +- Press `F` in Browse Mode to jump between checkboxes on the Accessibility settings page; each setting auto-saves when toggled +- After disabling hovercards, verify the change: navigate any repository page and confirm links no longer announce "Press H to preview" +- The Theme selector on the Appearance page is a set of radio buttons; press `Arrow Down` to cycle through themes and hear each name announced + +
+ +
+Low vision users + +- Choose "High contrast dark" or "High contrast light" under Appearance -- these themes increase border weight and icon contrast across all GitHub pages +- Enable "Link underlines" so links are visible without relying on color difference alone +- After changing themes, check the diff view on any pull request; some themes render additions/deletions with subtle shading that may need further zoom + +
+ +
+Sighted users + +- The Accessibility settings page is a single column of checkboxes near the bottom of the left sidebar in Settings +- Hovercards appear as floating cards when you hover on usernames or issues; turning them off removes that popup behavior +- After choosing a theme, scroll down on the Appearance page to preview how code blocks and diffs render in your chosen colors + +
+ + +## Step 3 - Configure Your Profile + +Your GitHub profile is your public identity in the open source community. Setting it up properly helps maintainers know who you are. + +### Who are maintainers? + +Maintainers are the people who manage a repository -- they review contributions, respond to issues, merge pull requests, and keep the project running. When you open an issue or submit a pull request, a maintainer is the person who will see it and respond. Setting up your profile helps maintainers know who you are and builds trust in the community. + +### Update your profile + +1. Navigate to [Settings → Public profile](https://github.com/settings/profile) +2. Fill in: + - **Name** - your real name or display name (not the same as your username) + - **Bio** - a short description (e.g., "Accessibility advocate and open source contributor") + - **Location** - optional but builds trust in the community + - **Website or social links** - optional + - **Pronouns** - GitHub supports adding pronouns to your profile + +### Add a profile picture (strongly recommended) + +A profile picture is strongly recommended because it humanizes your contributions and helps maintainers and collaborators recognize you across issues, pull requests, and comments. It can be a photo or any image that represents you. If you prefer not to use a photo, GitHub generates a default avatar based on your username. + +### Set your notification email + +1. Navigate to [Settings → Notifications](https://github.com/settings/notifications) +2. Add a **custom routing** email if you want GitHub notifications to go to a different address than your account email + + +## Step 4 - Check GitHub Feature Preview Settings + +GitHub continuously rolls out improvements to its interface. Some enhancements start as opt-in Feature Previews before becoming the standard experience. Three features matter most for screen reader users working through this workshop: + +- **New Issues Experience** - improves heading hierarchy, ARIA landmark structure, and live-region announcements on the Issues pages +- **New Files Changed Experience** - adds proper landmark structure, an accessible file tree, and better keyboard navigation to the Files Changed tab in Pull Requests +- **GitHub Command Palette** - a keyboard-first command launcher (`Ctrl+K` on Windows, `Cmd+K` on macOS) that lets you navigate to any repository, issue, PR, file, or page by typing its name. Faster than clicking through menus and fully accessible with screen readers + +Both have been broadly rolled out and may already be active on your account. Check before the workshop begins. + +### How to Check and Enable Feature Previews + +> Source: [accessibility.github.com/documentation/guide/issues/](https://accessibility.github.com/documentation/guide/issues/) and [accessibility.github.com/documentation/guide/pull-requests/](https://accessibility.github.com/documentation/guide/pull-requests/) + +
+Visual / mouse users + +1. Sign in to GitHub and go to any page +2. Click your **profile picture** (avatar) in the top-right corner +3. In the dropdown menu, click **Feature preview** +4. A panel opens on the right side of the screen listing available features +5. Click on **New Issues Experience** to expand its details +6. If an **Enable** button appears, click it. If you see **Disable**, the feature is already active - no action needed. +7. Return to the feature list and repeat for **New Files Changed Experience** + +
+ +
+Screen reader users (NVDA / JAWS) + +#### NVDA or JAWS (Windows) + +1. Sign into GitHub and open any page +2. Switch to Browse Mode if not already active (`NVDA+Space` / JAWS virtual cursor) +3. Press `H` or `Shift+H` to navigate to the **"Navigation Menu"** heading, or press `D` to navigate landmark regions to the navigation section +4. Press `B` to jump to buttons, navigating until you hear **"Open user navigation menu, button"** - this button is in the top-right corner of the page +5. Press `Enter` to activate it - a dropdown menu opens +6. Press `↓` or `K` to move through the menu items until you hear **"Feature preview"** +7. Press `Enter` to select it - the Feature Preview panel opens +8. Navigate through the list of features with `↓` or `I` (list item navigation) +9. When you reach **"New Issues Experience"**, press `Enter` or `Space` to select it - its detail panel expands +10. Press `Tab` to move to the end of the feature detail section, where you will find either: + - An **"Enable"** button - press `Enter` to enable the feature + - A **"Disable"** button - the feature is already enabled; no action needed +11. Go back and repeat steps 9-10 for **"New Files Changed Experience"** +12. Repeat again for **"GitHub Command Palette"** if it appears in the list + +
+ +
+Screen reader users (VoiceOver on macOS) + +1. Sign into GitHub and open any page +2. Press `VO+U` to open the Rotor and navigate to the Buttons list +3. Find **"Open user navigation menu"** and press `Enter` to activate it +4. Use `VO+Down Arrow` to navigate the dropdown until you hear **"Feature preview"** +5. Press `VO+Space` to activate it - the Feature Preview panel opens +6. Use `VO+Down Arrow` or `VO+Right Arrow` to navigate through the feature list +7. When you reach **"New Issues Experience"**, press `VO+Space` to select it +8. Press `Tab` to move to the end of the feature detail section +9. If you hear **"Enable"**, press `VO+Space` to activate it. If you hear **"Disable"**, it is already on. +10. Repeat for **"New Files Changed Experience"** +11. Repeat for **"GitHub Command Palette"** if it appears in the list + +
+ +### What "Not Listed" Means + +If you open Feature Preview and neither **"New Issues Experience"** nor **"New Files Changed Experience"** appears in the list at all - that is good news. It means both features have **graduated to the standard GitHub interface** and are active automatically for every user. No action needed. + +### What Each Feature Enables + +| Feature | What it improves for screen reader users | +| --------- | ------------------------------------------ | +| **New Issues Experience** | Issues list uses proper `
    ` list structure. Issue titles are h3 headings. ARIA live regions announce filter result updates. Toolbar uses arrow key navigation. Close issue via `Ctrl+Shift+Enter` from the comment box. | +| **New Files Changed Experience** | Files Changed tab includes a navigable file tree region. Diffs are structured as tables with row/column navigation. Filter changed files field is reachable with `E`. Inline comment mode activates with `Enter` on a focused diff line. | +| **GitHub Command Palette** | Press `Ctrl+K` (Windows) or `Cmd+K` (macOS) from any GitHub page to open a command palette. Type to search for repositories, issues, PRs, files, settings, or actions. Results appear in a list navigable with `Arrow` keys. Press `Enter` to go. Screen readers announce each result as you arrow through the list. Scope the search with prefixes: `#` for issues/PRs, `!` for projects, `>` for commands, `/` for files. | + +> **Why this matters:** Without these features enabled, the keyboard and screen reader workflows described throughout this workshop will not match what you see on screen. Enabling them before you begin ensures everything works as documented. + + +## Step 5 - Set Up Your Screen Reader & Browser + +### NVDA (Windows) + +**Install NVDA** if you haven't already: + +1. Download from [the NVDA download page](https://www.nvaccess.org/download/) +2. Run the installer - you can install to your computer or run portably +3. After launch, NVDA speaks "NVDA started" when running + +#### Configure NVDA for web browsing + +1. Open NVDA Menu (`NVDA+N`) +2. Go to **Preferences → Settings → Browse Mode** +3. Enable "Use screen layout" - this helps with GitHub's landmark navigation +4. Under **Document Formatting**, disable announcements you find too verbose + +#### Recommended NVDA voice settings + +- Rate: 60-75% (fast enough to be efficient, slow enough to be clear) +- Punctuation: "Most" (reads important symbols like `#` and `@` without reading every period) + +**Your NVDA key:** By default it is `Insert`. It can also be set to `Caps Lock` in NVDA preferences if that is more comfortable. + + +### JAWS (Windows) + +**If using a trial:** JAWS runs in 40-minute sessions without a license. Restart it if you need more time. + +#### Configure JAWS for web browsing + +1. Open JAWS Settings Center: `Insert+F2 → Settings Center` +2. Ensure "Virtual cursor" is active for web browsing +3. In Chrome or Firefox, JAWS should automatically activate Virtual/Browse mode + +#### Recommended JAWS settings for GitHub + +- Verbosity → Links: Read link text only (disable "opens in new window" if too verbose) +- Verbosity → Punctuation: "Most" for same reason as NVDA + +**Your JAWS key:** `Insert` (or `Caps Lock` if using laptop layout) + + +### VoiceOver (macOS) + +**Activate VoiceOver:** `Command+F5` toggles VoiceOver on and off. + +#### Essential VoiceOver setup for web + +1. Open VoiceOver Utility: `VO+F8` +2. Go to **Web** category → **Web Rotor** +3. Ensure these are checked: Headings, Landmarks, Links, Buttons, Form Controls, Tables +4. **Recommended browser:** Safari (best VoiceOver integration on macOS) +5. Firefox on macOS also has good VoiceOver support + +**Your VoiceOver modifier key:** `VO` = `Control+Option` by default. + +#### Turn on Quick Nav for fast navigation + +- Press `Left Arrow + Right Arrow` simultaneously to toggle Quick Nav +- With Quick Nav on: `H` = next heading, `L` = next link, `B` = next button (same as NVDA/JAWS browse mode keys) + +#### A note for Mac users about keyboard shortcuts + +Throughout this documentation, Windows keyboard shortcuts for VS Code are frequently referenced. In general, these keyboard shortcuts work on the Mac, however, Mac users should substitute `Command` whenever `Ctrl` is referenced. For example, Windows users might use the keyboard shortcut `Ctrl+Shift+P` to open the Command Palette. On the Mac, this keyboard shortcut would be `Command+Shift+P`. + +### Browser Recommendations Summary + +| Browser | Windows | macOS | Notes | +| --------- | --------- | ------- | ------- | +| **Chrome** | Recommended | Good | Best with NVDA and JAWS | +| **Firefox** | Recommended | Good | Excellent accessibility support on all platforms | +| **Edge** | Acceptable | Acceptable | Chromium-based; works well | +| **Safari** | Not available | Recommended | Best for VoiceOver on macOS | + +**Before the workshop:** Open GitHub.com in your chosen browser with your screen reader running and confirm you can navigate the page using heading keys. + +### Learning Cards: Set Up Your Screen Reader and Browser + +
    +Screen reader users + +- NVDA: press `NVDA+N` then `P` then `S` to reach Settings quickly; Browse Mode settings are under the "Browse Mode" category +- JAWS: press `Insert+F2` to open the Run JAWS Manager dialog, then type "Settings" to jump directly to Settings Center +- VoiceOver: press `VO+F8` to open VoiceOver Utility; add "Form Controls" to the Web Rotor list so you can jump to GitHub's search and filter fields + +
    + +
    +Low vision users + +- In Chrome, press `Ctrl+Plus` to zoom; GitHub's layout reflows cleanly up to 200% but the top navigation bar may collapse items into a hamburger menu at higher zoom +- Firefox's Reader View (`F9`) does not work on GitHub pages, so rely on browser zoom and GitHub's high-contrast themes instead +- On macOS, enable "Hover Text" in System Settings, Accessibility, Zoom to see enlarged text under the pointer without zooming the full screen + +
    + +
    +Sighted users + +- Chrome DevTools (`F12`) includes a "Rendering" panel where you can simulate vision deficiencies to preview how GitHub looks to other users +- Firefox and Chrome both support the `Tab` key for visible focus rings; if you do not see them, check that your OS "focus indicator" setting is not suppressed +- Safari on macOS has the tightest VoiceOver integration; if you use a Mac in the workshop, Safari is the safest default browser + +
    + + +## Step 6 - Install Git and Visual Studio Code + +> **See also:** [Chapter 01: Choose Your Tools](01-choose-your-tools.md) walks through every tool option with screen reader and low-vision guidance. + +### Install Git First + +> **VS Code does not install Git.** It detects whether Git is already on your system. If Git is missing, the Source Control panel will display a warning, and all `git` commands in the terminal will fail. Install Git before installing VS Code. + +> **Already have VS Code installed?** No problem -- you do not need to reinstall it. Just install Git using the instructions below, then restart VS Code. VS Code detects Git automatically on startup, so after a restart, the Source Control panel and all `git` commands in the terminal will work immediately. No extra configuration is needed. + +#### Windows + +1. Download the Git for Windows installer from [Git for Windows download page](https://git-scm.com/download/win) +2. Run the installer - default options are correct for most users +3. On the "Adjusting your PATH environment" screen, keep the default: **"Git from the command line and also from 3rd-party software"** +4. Complete the installer and restart any open terminals + +#### Verify installation (Windows) + +1. Open PowerShell or Command Prompt +2. Type `git --version` and press `Enter` +3. You should see a version number such as `git version 2.47.0.windows.2` - any version is fine + +#### macOS + +Git is often already present via Xcode Command Line Tools. To check: + +1. Open Terminal (`Cmd+Space` → type "Terminal") +2. Type `git --version` and press `Enter` +3. If Git is not installed, macOS will automatically prompt you to install Xcode Command Line Tools - follow the prompt and wait for it to complete +4. Alternatively, install directly from [Git for macOS download page](https://git-scm.com/download/mac) or via Homebrew: `brew install git` + +#### Screen reader note (Windows terminal verification) + +- PowerShell is accessible with all screen readers via Browse Mode or Forms Mode +- Type `git --version`, press `Enter`, then press `↑` to re-read the output line + +Once Git is installed, you will configure your Git identity in Step 7 after VS Code is set up. + + +### Install Visual Studio Code + +Visual Studio Code (VS Code) is the development environment used throughout this workshop. It is free, open source, and has excellent built-in accessibility support. + +### Download and install + +1. Navigate to [code.visualstudio.com](https://code.visualstudio.com/) +2. Select the download link for your operating system +3. Run the installer with default options +4. Launch VS Code when the installer finishes + +### Enable Screen Reader Mode in VS Code + +> **Do this before anything else in VS Code.** Screen Reader Mode changes how the editor renders content - without it, your screen reader may receive incomplete or fragmented output from the editor, diff views, and Copilot Chat. + +VS Code may detect your screen reader automatically when it first opens and ask if you want to enable this mode. If it does: + +1. Listen for the dialog - it will say something like "A screen reader is detected. Would you like to enable Screen Reader Optimized mode?" +2. Press `Enter` to accept, or `Tab` to the **Enable** button and press `Space` + +If VS Code did **not** prompt you automatically, enable it manually: + +#### Option A - Keyboard shortcut + +1. Press `Shift+Alt+F1` +2. VS Code toggles Screen Reader Optimized mode immediately + +#### Option B - Command Palette + +1. Press `Ctrl+Shift+P` to open the Command Palette + - Your screen reader will announce "Type to filter" or the palette input field +2. Type: `screen reader` - the list filters as you type +3. Arrow down to **"Accessibility: Toggle Screen Reader Accessibility Mode"** +4. Press `Enter` + +#### How to confirm it is on + +1. Press `Ctrl+Shift+P` to open the Command Palette again +2. Type: `screen reader optimized` +3. If the status bar at the bottom of the window is accessible to you, it will read **"Screen Reader Optimized"** +4. Alternatively: go to **File → Preferences → Settings** (`Ctrl+,`), type `screenReaderOptimized` in the search box, and verify the checkbox is ticked + +#### What Screen Reader Mode changes + +- The editor renders as a plain text region your screen reader can navigate linearly with arrow keys +- Audio cues are enabled for inline suggestions, errors, warnings, and folder expand/collapse +- Diffs are presented as readable before/after text instead of a visual side-by-side view +- The Copilot Chat response panel reads as a structured document + +> **Screen reader note:** Once Screen Reader Mode is on, you navigate the editor with `Up` and `Down Arrow` to move line by line. Press `Enter` to open a folded section. Press `Escape` to leave the editor and move focus back to the activity bar or panels. + +### VS Code keyboard basics (we will cover these fully in the workshop) + +| Action | Shortcut | +| -------- | ---------- | +| Open Command Palette | `Ctrl+Shift+P` | +| Open file | `Ctrl+P` | +| Open terminal | `` Ctrl+` `` (backtick) | +| Focus Explorer panel | `Ctrl+Shift+E` | +| Focus editor | `Ctrl+1` | + +### Learning Cards: Install Git and Visual Studio Code + +
    +Screen reader users + +- After installing VS Code, press `Shift+Alt+F1` immediately to enable Screen Reader Optimized mode; without it the editor area is not linearized for your screen reader +- Press `Ctrl+Shift+P` to open the Command Palette; it behaves like an autocomplete list -- type a few letters and press `Down Arrow` to browse matches +- The VS Code terminal (`` Ctrl+` ``) is a standard text area; press `Up Arrow` to review previous command output line by line + +
    + +
    +Low vision users + +- In VS Code, press `Ctrl+Plus` or `Ctrl+Minus` to zoom the entire interface; the zoom level persists across restarts +- Open Settings (`Ctrl+,`), search "editor.fontSize" and increase it to 18-24 for comfortable code reading alongside your browser zoom +- Choose a high-contrast theme: press `Ctrl+K Ctrl+T`, then select "High Contrast" or "High Contrast Light" from the list + +
    + +
    +Sighted users + +- The Activity Bar on the left edge of VS Code shows icons for Explorer, Search, Source Control, Run, and Extensions; hover each to see its name and shortcut +- A small Git icon with a number badge in the Activity Bar means VS Code detected Git successfully and is tracking changes +- The Status Bar at the bottom shows your current branch name on the left and encoding, language mode, and line/column on the right + +
    + + +## Step 7 - Configure Git Identity + +Now that Git is installed, tell it who you are. Git embeds your name and email in every commit you make, and this affects how your contributions appear in project history. + +### Configure in VS Code + +1. Open **Visual Studio Code** +2. Open the integrated terminal: + - Menu: **Terminal → New Terminal** + - Keyboard: `` Ctrl+` `` (Windows) or `` Cmd+` `` (Mac) +3. Type the following commands, replacing with your information: + +```bash +git config --global user.name "Your Name" +git config --global user.email "your-email@example.com" +``` + +#### What to use + +- **user.name:** Your real name or the name you want shown on commits (e.g., "Jane Smith") +- **user.email:** The email address associated with your GitHub account (must match exactly) + +**Screen reader note:** The terminal in VS Code is accessible with all major screen readers. Press `` Ctrl+` `` to move focus to the terminal, type your commands, and press `Enter`. + +### Why This Matters + +If Git isn't configured, it will either: + +- Use a default name like "Unknown" (looks unprofessional in project history) +- Refuse to create commits with an error message + +### Verify Your Configuration + +Run this command to see your current settings: + +```bash +git config --global --list +``` + +You should see: + +```text +user.name=Your Name +user.email=your-email@example.com +``` + +### Using the Correct Email + +Use the same email you registered with GitHub. If you're concerned about privacy, GitHub offers a no-reply email you can use: `username@users.noreply.github.com` - find it in [Settings → Emails](https://github.com/settings/emails). + + +## Step 8 - Install VS Code Extensions + +This workshop uses two VS Code extensions. GitHub Copilot is built into VS Code automatically. The GitHub Pull Requests extension needs to be installed manually. Both authenticate through your browser session - if you are signed into GitHub in your web browser, VS Code picks up the session automatically. + + +### GitHub Copilot (Built In) + +GitHub Copilot is automatically included with Visual Studio Code. There is no extension to install separately. It provides both inline code completions and the conversational Agent mode panel used throughout the second half of the workshop. + +#### Activate Copilot + +1. Make sure Screen Reader Mode is enabled (see above) +2. Make sure you are signed into GitHub in your web browser +3. Press `Ctrl+Shift+I` to open Agent mode + - Your screen reader should announce the chat input field +4. Type: `Hello` and press `Enter` +5. VS Code will automatically sign you into GitHub Copilot using your browser session - no manual sign-in command is needed +6. A response will appear in the chat history above the input field +7. Navigate up with `Shift+Tab` or `Up Arrow` to read the response + +> **That is it.** You do not need to use the Command Palette to sign in. If you are logged into GitHub in your browser, VS Code handles authentication automatically when you first interact with the agent. + + +### Extension 2 - GitHub Pull Requests + +This extension lets you review and manage pull requests without leaving VS Code. It is used in the code review chapters. + +#### Install + +1. Press `Ctrl+Shift+X` to open the Extensions panel +2. Type: `GitHub Pull Requests` +3. Press `Tab` to move into the results list +4. Arrow down to find **"GitHub Pull Requests"** with publisher **"GitHub"** + - This extension was formerly named "GitHub Pull Requests and Issues" - either name is correct + +> **Extension imposter warning:** The VS Code Marketplace contains third-party extensions with similar names. Always verify the **publisher** before installing. The correct extensions for this workshop are: +> +> - **GitHub Pull Requests** - publisher must be **GitHub** (verified badge) +> - **GitHub Copilot** - publisher must be **GitHub** (built in, no manual install needed) +> +> If the publisher name says anything other than "GitHub" (for example, a personal username or an unfamiliar company), **do not install it**. A screen reader user can verify the publisher: after arrowing to a search result, `Tab` forward past the extension name to hear "Publisher: GitHub" or similar. If you accidentally install a wrong extension, press `Ctrl+Shift+X`, find it, and select **Uninstall**. +5. Press `Enter` to open the details page +6. Press `Tab` to the **Install** button and press `Enter` or `Space` +7. VS Code will announce when installation is complete + +#### Verify it is working + +1. Press `Ctrl+Shift+P` and type: `GitHub Pull Requests: Sign in` + - If you are already signed in from the earlier step, this command may not appear - that means you are already authenticated +2. To confirm the extension loaded: press `Ctrl+Shift+P`, type `GitHub Pull Requests: Focus on Pull Requests View` + - The Pull Requests panel should open in the sidebar + - If your repository has open pull requests, they will appear here + +> **Screen reader note:** The Pull Requests panel is a tree view. Navigate it with `Up` and `Down Arrow`. Press `Enter` or `Right Arrow` to expand a node. + + +### Copilot Free tier + +Copilot Free is available to all GitHub users at no cost. It includes: + +- Limited inline code completions per month +- Limited Copilot Chat messages per month + +For this workshop, Free tier is sufficient. If you want unlimited access, paid plans are available at [GitHub Copilot pricing](https://github.com/features/copilot#pricing). + +### Learning Cards: Install VS Code Extensions + +
    +Screen reader users + +- In the Extensions panel (`Ctrl+Shift+X`), type your search, press `Tab` to enter the results list, then `Down Arrow` through results; each announces the extension name and publisher +- Verify the publisher is "GitHub" before installing; after arrowing to a result, press `Tab` once to hear the publisher name announced +- To confirm Copilot is active, press `Ctrl+Shift+I` to open Agent mode; your screen reader should announce the chat input field within two seconds + +
    + +
    +Low vision users + +- Extension search results show the publisher name in smaller grey text beneath the extension name; zoom to 150%+ to read it clearly +- The Install button is blue and appears on the right side of each extension card; after installation it changes to a gear icon for settings +- The Copilot icon in the Status Bar (bottom right, a small two-sparkle icon) turns solid when Copilot is authenticated and active + +
    + +
    +Sighted users + +- Look for the blue verified badge (checkmark) next to "GitHub" in the publisher field to confirm you have the official extension +- After installing the Pull Requests extension, a new GitHub icon appears in the Activity Bar on the left; click it to see open PRs for the current repo +- The Copilot chat panel opens on the right side when you press `Ctrl+Shift+I`; the sparkle icon in the editor gutter means Copilot has an inline suggestion + +
    + + +## Step 9 - Verification Checklist + +### Tool Cards: Verify Your Setup + +**github.com (browser):** +Sign in at github.com and verify your profile, accessibility settings, and that you can navigate with keyboard shortcuts (`G I` for Issues, `G P` for Pull Requests). + +**VS Code Desktop:** +Open VS Code and confirm: Screen Reader Mode is on (`Shift+Alt+F1`), Git is detected (run `git --version` in the terminal), and the GitHub Pull Requests extension is installed. + +**GitHub Desktop:** +Open GitHub Desktop, sign in with your GitHub account, and verify it shows your repositories list. + +**Git CLI (terminal):** +```bash +git --version +git config user.name +git config user.email +gh auth status # if GitHub CLI is installed +``` + +Work through this checklist before Day 1. Check off each item: + +```text +Pre-Workshop Checklist + +GITHUB ACCOUNT +[ ] GitHub account created and email verified +[ ] Two-factor authentication enabled +[ ] Profile name, bio set + +GITHUB SETTINGS +[ ] Accessibility settings page visited +[ ] Hovercards / link previews turned OFF +[ ] Theme set to your preferred option +[ ] Confirmed modern GitHub Issues and Pull Request experience is working (see Step 4 - may already be active or enabled via Feature preview) + +BROWSER & SCREEN READER +[ ] Screen reader installed and working (NVDA / JAWS / VoiceOver) +[ ] Browser chosen: Chrome, Firefox, Edge (Windows) or Safari (macOS) +[ ] Navigated to github.com with screen reader - page announces headings and landmarks +[ ] Can navigate the GitHub homepage using heading keys (H) without a mouse + +GIT & VS CODE (required before the workshop) +[ ] Git installed and verified (run git --version in a terminal) +[ ] Git identity configured (git config --global user.name and user.email) +[ ] Visual Studio Code installed +[ ] Screen Reader Mode enabled in VS Code (Shift+Alt+F1 or Command Palette) +[ ] Signed into GitHub in your web browser +[ ] GitHub Copilot responds in Agent mode (Ctrl+Shift+I, type Hello, get a response) +[ ] GitHub Pull Requests extension installed (publisher: GitHub) +[ ] Pull Requests panel opens (Ctrl+Shift+P → "Focus on Pull Requests View") +``` + +### What Happens at the Start of Day 1 + +You do **not** need to claim a workshop repository before Day 1 -- that is the very first hands-on step we do together in Block 0. When the workshop opens, the facilitator will paste a **GitHub Classroom assignment link** in the chat. Accepting that link creates your own private Learning Room repository in the workshop organization and seeds it with Challenge 1. + +The full guided walkthrough lives in [Chapter 4: Step-by-Step: Accept Your Classroom Assignment and Open Your Repo](04-the-learning-room.md#step-by-step-accept-your-classroom-assignment-and-open-your-repo). Skim it the night before if you want to know what to expect; we will walk through it live in Block 0. + + +## Other GitHub Access Methods (Reference Only) + +This workshop focuses entirely on GitHub.com in the browser and VS Code. However, you should be aware that other ways to work with GitHub exist. We list them here for your reference - we will not be teaching these in depth. + +### GitHub Desktop + +A graphical desktop application for managing repositories, branches, and commits without using the command line. + +- Download: [desktop.github.com](https://desktop.github.com/) +- Provides a visual interface for cloning, committing, pushing, and creating PRs +- Has some screen reader support, though the web interface is generally more accessible +- A good option for those who prefer a visual GUI over the command line + +### GitHub CLI (`gh`) + +A command-line tool that lets you perform nearly any GitHub action directly from your terminal. + +```bash +# Examples (reference only - not covered in this workshop) +gh repo clone owner/repo +gh issue create +gh pr create +gh pr review +gh pr merge +``` + +- Download: [cli.github.com](https://cli.github.com/) +- Excellent for automation and scripting +- Very accessible - terminal/command-line interfaces work well with screen readers +- Full documentation: [cli.github.com/manual](https://cli.github.com/manual/) + +### GitHub Copilot CLI (`gh copilot`) + +An extension to the GitHub CLI that brings Copilot assistance to the terminal. You can ask it to explain or suggest shell commands in plain English. + +```bash +# Reference examples only +gh copilot suggest "how do I undo my last commit" +gh copilot explain "git rebase -i HEAD~3" +``` + +- Install: `gh extension install github/gh-copilot` +- Documentation: [docs.github.com/en/copilot/github-copilot-in-the-cli](https://docs.github.com/en/copilot/github-copilot-in-the-cli/about-github-copilot-in-the-cli) +- Particularly useful for users who prefer a terminal workflow + +### Git (the version control system itself) + +GitHub is a platform built on top of **Git**, which is the underlying version control system. Git runs locally on your computer via a terminal. + +We are not covering Git commands in this workshop. If you want to learn Git, these are excellent starting points: + +- [Git Handbook](https://guides.github.com/introduction/git-handbook/) +- [Pro Git book (free)](https://git-scm.com/book/en/v2) +- [GitHub Skills: Introduction to GitHub](https://github.com/skills/introduction-to-github) + + +## If You Get Stuck + +| Problem | What to do | +|---|---| +| GitHub signup verification puzzle fails | Refresh the page and try again. Some puzzles are audio-based: look for an audio button. If it fails three times, try a different browser. | +| Two-factor authentication codes not arriving | Check your spam folder. If using an authenticator app, verify the time on your phone is correct (auto-sync). | +| Git not found after installing | Close and reopen your terminal. On Windows, restart VS Code. Run `git --version` to confirm. | +| VS Code does not detect screen reader | Press `Shift+Alt+F1` (Windows) or run "Toggle Screen Reader Mode" from the Command Palette. | +| Copilot does not respond in Agent mode | Verify you are signed in to GitHub in VS Code. Check that Copilot is enabled in your GitHub account settings. | +| Cannot install VS Code extensions | Check your internet connection. Try installing from the terminal: `code --install-extension GitHub.vscode-pull-request-github`. | +| Everything else | File an issue at [community-access/git-going-with-github](https://github.com/community-access/git-going-with-github/issues) describing what step you are on and what happened. We will help. | + + +## Getting Help Before the Event + +If you cannot complete any step in this guide before the workshop: + +1. **File an issue** - [community-access/git-going-with-github](https://github.com/community-access/git-going-with-github/issues) - we will help you get set up +2. **File an issue in this repository** - describe exactly what step you are on and what is not working +3. **Join the GitHub Accessibility Discussions** - [GitHub Community Accessibility Discussions](https://github.com/orgs/community/discussions/categories/accessibility) - the community is helpful and welcoming + +You will not be left behind. Every setup issue we can solve before Day 1 means more time for learning on the day. + + +> **Next Step:** You are all set up! Move on to [Chapter 01: Choose Your Tools](01-choose-your-tools.md). + +--- + + +*Next: [Chapter 01: Choose Your Tools](01-choose-your-tools.md)* +*Back: [Course Guide](course-guide.md)* +*Related appendices: [Appendix D: Git Authentication](appendix-d-git-authentication.md) | [Appendix Y: Workshop Materials](appendix-y-workshop-materials.md)* + diff --git a/admin/qa-bundle/docs/01-choose-your-tools.md b/admin/qa-bundle/docs/01-choose-your-tools.md new file mode 100644 index 0000000..1b67153 --- /dev/null +++ b/admin/qa-bundle/docs/01-choose-your-tools.md @@ -0,0 +1,491 @@ +# Choose Your Adventure: A Tool Tour + +> **Related appendices:** [Appendix G: VS Code Reference](appendix-g-vscode-reference.md) | [Appendix H: GitHub Desktop](appendix-h-github-desktop.md) | [Appendix I: GitHub CLI](appendix-i-github-cli.md) | [Appendix J: Codespaces](appendix-j-cloud-editors.md) +> **Authoritative sources:** [VS Code Docs: Setup](https://code.visualstudio.com/docs/setup/setup-overview) | [GitHub Desktop Docs](https://docs.github.com/en/desktop) | [GitHub CLI Manual](https://cli.github.com/manual/) + + +> **Day 1, Opening Material** +> +> Before you write your first line of code, you need to know what tools are available and which ones match the way you work. This chapter is a guided tour of the five tool environments you can use throughout this workshop. You do not need to install anything right now -- just explore what is available so you can make confident choices later. + +## Table of Contents + +1. [Why This Matters](#1-why-this-matters) +2. [The Five Paths](#2-the-five-paths) +3. [Path 1: GitHub.com (Browser)](#3-path-1-githubcom-browser) +4. [Path 2: github.dev (Browser-Based Editor)](#4-path-2-githubdev-browser-based-editor) +5. [Path 3: VS Code (Desktop)](#5-path-3-vs-code-desktop) +6. [Path 4: GitHub Desktop](#6-path-4-github-desktop) +7. [Path 5: GitHub CLI](#7-path-5-github-cli) +8. [Which Path Should I Start With?](#8-which-path-should-i-start-with) +9. [Your First Confidence Exercise](#9-your-first-confidence-exercise) +10. [If You Get Stuck](#10-if-you-get-stuck) + +--- + +## 1. Why This Matters + +There is no single "right" way to use GitHub. Some people prefer a browser. Some prefer a desktop application. Some prefer a terminal. Some switch between all of them depending on the task. + +The workshop is designed so that every exercise can be completed using any of the five paths described below. When a chapter gives step-by-step instructions, it always covers at least the browser path and one local path. In later chapters, you will see **tool cards** -- expandable blocks that show how to complete a step using each tool. + +Your job in this chapter is not to pick one path forever. It is to understand what each path offers so that when a chapter says "open the file," you know where that happens in your tool of choice. + +> **Screen reader note:** Every path in this chapter is described by its interface behavior, not its visual appearance. If a path works well with your screen reader, that information is stated up front. + +--- + +## 2. The Five Paths + +The following table summarizes all five environments at a glance. Read through the summaries first, then explore the sections that interest you. + +| Path | What It Is | Needs Installation? | Best For | +|---|---|---|---| +| **GitHub.com** | The GitHub website in your browser | No | Issues, pull requests, repository navigation, code review | +| **github.dev** | A VS Code editor that runs inside your browser | No | Editing files, multi-file changes, quick commits | +| **VS Code** | A desktop code editor with Git built in | Yes | Full development, extensions, terminal, Copilot | +| **GitHub Desktop** | A desktop Git client with a visual interface | Yes | Branching, committing, and syncing without typing commands | +| **GitHub CLI** | A command-line tool called `gh` | Yes | Scripting, automation, power users who prefer the terminal | + +> **You do not need all five.** Most students start with GitHub.com (Path 1) on Day 1 and add VS Code (Path 3) on Day 2. The other paths are available if they match your workflow. + +--- + +## 3. Path 1: GitHub.com (Browser) + +**What it is:** The GitHub website at [github.com](https://github.com). Every repository, issue, pull request, and setting lives here. If you have a browser, you have GitHub. + +**No installation required.** Sign in at github.com and you are ready. + +### What you can do here + +- Browse repositories, files, and folders +- Create, comment on, and close issues +- Open, review, and merge pull requests +- Edit individual files using the built-in web editor (pencil icon) +- Manage labels, milestones, and project boards +- Configure repository settings and branch protection + +### What you cannot do here + +- Run code or tests locally +- Use a full-featured code editor with extensions +- Make offline changes + +### Screen reader experience + +GitHub.com has strong screen reader support. Every page uses ARIA landmarks, headings follow a consistent hierarchy, and keyboard shortcuts are available for most actions. + +Key navigation patterns: + +| Action | How to do it | +|---|---| +| Jump to main content | `S` shortcut on any page, or navigate to the "main" landmark | +| Open search | `/` or `S` key | +| Navigate tabs (Code, Issues, PRs) | `D` to the "Repository navigation" landmark, then arrow keys | +| Jump between headings | `H` key in browse mode | +| Jump between landmarks | `D` key in browse mode | + +> **Screen reader tip:** [Chapter 2](02-understanding-github.md) covers GitHub's page structure in full detail. If you are new to GitHub with a screen reader, read that chapter next. + +### Low vision experience + +GitHub supports light and dark themes, high contrast themes, and responds to your operating system's contrast preferences. To configure your preferred theme: + +1. Go to [github.com/settings/appearance](https://github.com/settings/appearance) +2. Choose from Light, Dark, Light high contrast, or Dark high contrast +3. Or select "Sync with system" to follow your OS setting + +GitHub's layout adapts to browser zoom up to 400% without horizontal scrolling on most pages. + +### Learning Cards: GitHub.com (Browser) + +
    +Screen reader users + +- Press `S` on any GitHub page to jump to the main search field; press `/` as an alternative +- Press `D` in Browse Mode to jump between ARIA landmark regions; the repository tabs (Code, Issues, Pull Requests) are inside the "Repository navigation" landmark +- Press `G` then `I` (two keystrokes in sequence) to jump directly to the Issues tab from anywhere in a repository + +
    + +
    +Low vision users + +- Switch to "High contrast dark" or "High contrast light" at github.com/settings/appearance for maximum border and text contrast +- Browser zoom up to 200% keeps GitHub's layout intact; above 200% the repository sidebar collapses into a hamburger menu +- Enable "Link underlines" in GitHub Accessibility settings so links are distinguishable without color + +
    + +
    +Sighted users + +- The repository navigation tabs (Code, Issues, Pull Requests, etc.) appear as a horizontal bar just below the repository name +- Code files turn into clickable links in the file tree; folders show a folder icon and files show a document icon +- The green "Code" dropdown button on the repository home page is where you find clone URLs and the "Open with github.dev" option + +
    + +--- + +## 4. Path 2: github.dev (Browser-Based Editor) + +**What it is:** A VS Code editor that runs entirely in your browser. Open any repository by pressing the `.` key on its GitHub page, or by changing `github.com` to `github.dev` in the URL. + +**No installation required.** Same browser, same sign-in, richer editor. + +### What you can do here + +- Edit multiple files in a VS Code-like interface with a file explorer, tabs, and an integrated terminal preview +- View file diffs and stage changes +- Commit directly to a branch +- Use many VS Code extensions that run in the browser + +### What you cannot do here + +- Run code, build projects, or execute terminal commands (the terminal is read-only for Git operations) +- Use extensions that require a local runtime (debuggers, compiled tools) +- Work offline + +### How to open it + +| Method | Steps | +|---|---| +| From any repo page | Press the `.` (period) key on your keyboard | +| From the URL bar | Change `github.com` to `github.dev` in the URL | +| From a file | While viewing a file on GitHub.com, press `.` to open it in the editor | + +### Screen reader experience + +github.dev is VS Code running in the browser, so the same keyboard navigation and screen reader support applies. The command palette (`Ctrl+Shift+P` or `Cmd+Shift+P`) is available, and all editor keybindings work. + +> **Note:** Some screen readers may need to switch to focus mode or application mode to interact with the editor area. If keystrokes are not reaching the editor, try pressing `Escape` to ensure focus is in the editor, then `Ctrl+Shift+P` for the command palette. + +### When to use github.dev over GitHub.com + +Use github.dev when you need to edit more than one file in a single commit, or when you want the code editor experience without installing anything. For single-file edits, the pencil icon on GitHub.com is simpler. + +--- + +## 5. Path 3: VS Code (Desktop) + +**What it is:** Visual Studio Code is a free desktop code editor from Microsoft. It has built-in Git support, an integrated terminal, thousands of extensions, and GitHub Copilot included. + +**Installation required.** Download from [code.visualstudio.com](https://code.visualstudio.com/). Installation is covered in [Chapter 0, Step 6](00-pre-workshop-setup.md#step-6---install-git-and-visual-studio-code). + +### What you can do here + +- Edit files with full IntelliSense, syntax highlighting, and extension support +- Use the integrated terminal to run Git commands, scripts, and programs +- Stage, commit, push, and pull using the Source Control panel or the terminal +- Run and debug code +- Use GitHub Copilot for code suggestions, chat, and code review +- Work offline (Git operations sync when you reconnect) + +### What you cannot do here (without extensions) + +- Manage GitHub issues and pull requests directly (install the [GitHub Pull Requests extension](https://marketplace.visualstudio.com/items?itemName=GitHub.vscode-pull-request-github) for this) +- View repository insights or settings (use GitHub.com for that) + +### Screen reader experience + +VS Code has a dedicated accessibility mode that activates automatically when a screen reader is detected. Key features: + +- Screen reader optimized mode announces line content, cursor position, and editor state +- The Accessibility Help dialog (`Alt+F1` or `Option+F1`) is available in every view +- All panels are reachable via keyboard shortcuts: + +| Panel | Shortcut (Windows/Linux) | Shortcut (macOS) | +|---|---|---| +| File Explorer | `Ctrl+Shift+E` | `Cmd+Shift+E` | +| Source Control | `Ctrl+Shift+G` | `Cmd+Shift+G` | +| Terminal | `` Ctrl+` `` | `` Cmd+` `` | +| Command Palette | `Ctrl+Shift+P` | `Cmd+Shift+P` | +| Extensions | `Ctrl+Shift+X` | `Cmd+Shift+X` | +| Problems panel | `Ctrl+Shift+M` | `Cmd+Shift+M` | + +> **Deep dive:** [Chapter 11](11-vscode-interface.md) covers the VS Code interface in detail. [Chapter 12](12-vscode-accessibility.md) covers accessibility-specific configuration. [Appendix G](appendix-g-vscode-reference.md) is the quick-reference card. + +### Low vision experience + +VS Code supports high contrast themes, custom zoom levels (`Ctrl+=` to zoom in, `Ctrl+-` to zoom out), and configurable font sizes. The minimap (the small code preview on the right side of the editor) can be disabled if it is distracting: open the command palette, type "minimap," and toggle the setting. + +### Learning Cards: VS Code (Desktop) + +
    +Screen reader users + +- Press `Ctrl+Shift+E` to focus the File Explorer tree; `Up/Down Arrow` navigates files, `Enter` opens a file, `Right Arrow` expands a folder +- Press `Ctrl+Shift+G` to focus Source Control; the tree lists changed files and each item announces its Git status (modified, untracked, etc.) +- Press `Alt+F1` inside any view to open the Accessibility Help dialog, which lists every keyboard shortcut for that specific panel + +
    + +
    +Low vision users + +- Press `Ctrl+K Ctrl+T` to open the theme picker; "High Contrast" and "High Contrast Light" offer the strongest visual differentiation +- Press `Ctrl+=` repeatedly to zoom the entire interface; the zoom level persists after restart +- Disable the minimap to reclaim screen width: `Ctrl+Shift+P`, type "minimap", toggle "Editor: Minimap Enabled" off + +
    + +
    +Sighted users + +- The Activity Bar (left edge) shows icons for Explorer, Search, Source Control, Run/Debug, and Extensions; a dot badge means there is activity in that panel +- The Status Bar (bottom edge) shows your current Git branch on the far left and sync status (cloud icon with arrows) next to it +- Click the split-editor icon (top right of any tab) to view two files side by side for comparison + +
    + +--- + +## 6. Path 4: GitHub Desktop + +**What it is:** A desktop application that provides a graphical interface for Git operations. Instead of typing `git commit` in a terminal, you use buttons, lists, and visual diffs. + +**Installation required.** Download from [desktop.github.com](https://desktop.github.com/). See [Appendix H](appendix-h-github-desktop.md) for setup details. + +### What you can do here + +- Clone repositories with one click +- Create, switch, and merge branches +- View file diffs in a side-by-side or unified view +- Stage individual files or specific lines within a file +- Commit with a message and push to GitHub +- Open pull requests (launches GitHub.com) + +### What you cannot do here + +- Edit code (GitHub Desktop is a Git client, not a code editor -- it opens your preferred editor) +- Review pull requests with inline comments +- Manage issues, labels, or project boards + +### Screen reader experience + +GitHub Desktop uses Electron and provides basic screen reader support. Branch switching, commit history, and file lists are navigable. However, the diff viewer has limited screen reader support compared to the VS Code diff viewer or the GitHub.com Files Changed tab. + +> **Recommendation for screen reader users:** GitHub Desktop works best as a companion to VS Code or a text editor. Use VS Code for editing and reviewing diffs, and GitHub Desktop for visual branch management if you prefer a graphical tool. + +### When to choose GitHub Desktop + +Choose GitHub Desktop if you prefer a visual representation of branches and commits, and you do not want to memorize Git commands. It is a good stepping stone between the GitHub.com web editor and the full VS Code workflow. + +--- + +## 7. Path 5: GitHub CLI + +**What it is:** A command-line tool called `gh` that brings GitHub features to your terminal. It handles authentication, issue management, pull request workflows, and repository operations -- directly from the command line. + +**Installation required.** Install via `winget install GitHub.cli` (Windows), `brew install gh` (macOS), or see [Appendix I](appendix-i-github-cli.md) for full instructions. + +### What you can do here + +- Create, view, and close issues: `gh issue create`, `gh issue view 42` +- Open, review, merge PRs: `gh pr create`, `gh pr review`, `gh pr merge` +- Clone repos and manage branches: `gh repo clone owner/repo` +- View CI/CD status: `gh run list`, `gh run view` +- Manage repository settings, labels, and releases +- Automate workflows with shell scripts + +### What you cannot do here + +- Edit files (the CLI manages GitHub operations, not file editing -- use your preferred editor) +- View visual diffs (use `git diff` for text-based diffs, or VS Code for a richer view) + +### Screen reader experience + +The GitHub CLI is a text-based tool running in a terminal. Screen reader users read its output directly as plain text -- no landmarks, headings, or ARIA to worry about. Output is generally well-formatted with tables and structured text. + +> **Tip for terminal users:** The `gh` command integrates with `git` seamlessly. After running `gh repo clone`, all standard `git` commands work in the cloned directory. You can mix `git` and `gh` commands freely. + +### When to choose GitHub CLI + +Choose the CLI if you are comfortable in a terminal and want fast, scriptable access to GitHub features. It pairs well with VS Code's integrated terminal, giving you the best of both worlds. + +### Learning Cards: GitHub CLI + +
    +Screen reader users + +- CLI output is plain text; use `Up Arrow` to re-read previous lines or pipe output through `more` to page through long results +- Run `gh issue list --state open` and output reads as a tab-separated table; each row is one line your screen reader can navigate +- Use `gh pr view --web` to open the current PR directly in your browser where full ARIA landmarks are available + +
    + +
    +Low vision users + +- Increase terminal font size in VS Code: Settings (`Ctrl+,`), search "terminal.integrated.fontSize" and set to 18-24 +- Use `gh pr diff` to view diffs in the terminal with colored additions (green) and deletions (red); if colors are hard to see, pipe through `less -R` for paginated output +- Set your terminal theme to high contrast in VS Code's theme picker (`Ctrl+K Ctrl+T`) to improve command and output readability + +
    + +
    +Sighted users + +- The `gh` tool uses colored output by default: green for success, red for errors, yellow for warnings +- Run `gh repo view --web` to instantly open the current repository's GitHub page in your browser +- Tab completion is available after running `gh completion -s powershell | Out-String | Invoke-Expression` in PowerShell + +
    + +--- + +## 8. Which Path Should I Start With? + +There is no wrong answer, but here is practical guidance based on when different tools become most useful in the workshop. + +### Day 1 recommendation + +| Your comfort level | Recommended starting path | Why | +|---|---|---| +| New to GitHub, new to coding | **GitHub.com (browser)** | Everything happens in one window. No installs. Clear, labeled interface. | +| Some web experience, want to edit files | **GitHub.com + github.dev** | Use the browser for navigation, press `.` to edit when needed. | +| Already use VS Code | **VS Code + GitHub.com** | Edit locally, use the browser for issues and PRs. | + +### Day 2 recommendation + +On Day 2, you work with Git locally. Most students add VS Code (Path 3) at this point: + +| Your Day 1 path | Day 2 addition | How they work together | +|---|---|---| +| GitHub.com only | Add **VS Code** | Clone the repo, edit locally, push changes, review PRs in the browser | +| GitHub.com + github.dev | Add **VS Code** | Transition from browser editing to local editing with full tool support | +| VS Code already | Add **GitHub CLI** (optional) | Speed up repetitive operations like creating issues and PRs | + +### Switching paths is normal + +You will likely use more than one tool during the workshop. The tools complement each other: + +- **Browse** the repository on GitHub.com to understand its structure +- **Edit** files in VS Code or github.dev for a better coding experience +- **Manage** branches in GitHub Desktop if you prefer the visual workflow +- **Automate** repetitive tasks with the GitHub CLI + +The workshop chapters always tell you which tool to use for each step. If a step says "open the file in your editor," use whichever editor you chose. + +### Learning Cards: Which Path Should I Start With? + +
    +Screen reader users + +- Start with GitHub.com on Day 1; its ARIA landmarks, heading hierarchy, and single-key shortcuts (`G I` for Issues, `G P` for Pull Requests) provide the most navigable experience +- When Day 2 adds VS Code, press `Shift+Alt+F1` immediately to enable Screen Reader Optimized mode before doing anything else +- You can switch tools mid-exercise; the workshop always tells you which tool each step targets, so look for the tool name at the start of each instruction + +
    + +
    +Low vision users + +- GitHub.com at 150-200% zoom with a high-contrast theme is the easiest starting environment; no installation needed +- When you add VS Code on Day 2, set both the editor zoom (`Ctrl+=`) and the font size (Settings, "editor.fontSize") independently for maximum comfort +- GitHub Desktop's visual branch diagram uses thin colored lines; if those are hard to see, stick with VS Code's Source Control panel which uses text labels + +
    + +
    +Sighted users + +- Start with GitHub.com to learn the layout; the repository tabs, file tree, and right-hand sidebar become familiar quickly +- On Day 2, VS Code's split-pane layout lets you view the terminal and editor side by side, which speeds up the Git workflow +- If you like visual branch history, GitHub Desktop draws branches as colored lines in a timeline; VS Code's Source Control panel is text-based by default + +
    + +--- + +## 9. Your First Confidence Exercise + +This exercise takes approximately five minutes. It verifies your tool is working and builds your confidence before Day 1 begins. + +### The task + +Open the public workshop curriculum repository and find the README file. + +### Path 1: GitHub.com + +1. Go to [github.com/Community-Access/git-going-with-github](https://github.com/Community-Access/git-going-with-github). +2. The README is displayed below the file list on the repository's home page. +3. Screen reader users: press `H` to navigate headings. The README's first heading announces the repository name. +4. You are done when you can read the first paragraph of the README. + +### Path 2: github.dev + +1. Go to [github.dev/Community-Access/git-going-with-github](https://github.dev/Community-Access/git-going-with-github). +2. The file explorer opens on the left. Press `Ctrl+Shift+E` (or `Cmd+Shift+E`) to focus it. +3. Navigate to `README.md` and press `Enter` to open it in a tab. +4. You are done when the file content appears in the editor. + +### Path 3: VS Code (if set up) + +1. Open VS Code. +2. Open the command palette: `Ctrl+Shift+P` (or `Cmd+Shift+P`). +3. Type "Git: Clone" and press `Enter`. +4. Paste the URL: `https://github.com/Community-Access/git-going-with-github.git` +5. Choose a folder to clone into and wait for the download. +6. When it finishes, VS Code offers to open the repository. Accept. +7. Open the file explorer (`Ctrl+Shift+E`) and select `README.md`. +8. You are done when the file content appears in the editor. + +### Path 4: GitHub Desktop + +1. Open GitHub Desktop. +2. Go to File, then Clone repository (or press `Ctrl+Shift+O`). +3. Paste the URL: `https://github.com/Community-Access/git-going-with-github.git` +4. Choose a local path and click Clone. +5. Once cloned, the repository appears in GitHub Desktop. Click "Open in Visual Studio Code" (or your preferred editor) to read the README. + +### Path 5: GitHub CLI + +1. Open your terminal. +2. Run: + +```bash +gh repo clone Community-Access/git-going-with-github +cd learning-room +``` + +3. Open the README in your preferred way: + +```bash +cat README.md # print to terminal +code README.md # open in VS Code +``` + +4. You are done when you can read the first paragraph. + +### What success looks like + +You opened a real repository and found a real file. That is the core action of this entire workshop -- everything else builds on it. + +--- + +## 10. If You Get Stuck + +| Problem | What to try | +|---|---| +| Cannot sign in to GitHub.com | Verify your email and password. Check [Chapter 0, Step 1](00-pre-workshop-setup.md#step-1---create-your-github-account). | +| github.dev does not open | Ensure you are signed in to GitHub.com first. Some browsers block the redirect -- try Chrome or Firefox. | +| VS Code is not installed | Follow [Chapter 0, Step 6](00-pre-workshop-setup.md#step-6---install-git-and-visual-studio-code). | +| Git clone fails | Check your internet connection. Verify Git is installed: run `git --version` in a terminal. See [Appendix D](appendix-d-git-authentication.md) for authentication issues. | +| Screen reader does not announce page content | Ensure browse mode is active (NVDA: press `Escape`; JAWS: press `Num Pad Plus`). Maximize the browser window. | +| Not sure which path to choose | Start with GitHub.com in your browser. You can always add more tools later. | +| GitHub Desktop cannot find the repo | Verify the URL is correct and your GitHub account has access to the repository. | +| GitHub CLI says "not authenticated" | Run `gh auth login` and follow the prompts. See [Appendix I](appendix-i-github-cli.md). | + + +> **Next Step:** Start your learning journey with [Chapter 02: Understanding GitHub](02-understanding-github.md). + +--- + + +*Next: [Chapter 02: Understanding GitHub](02-understanding-github.md)* +*Back: [Chapter 00: Pre-Workshop Setup](00-pre-workshop-setup.md)* +*Related appendices: [Appendix H: GitHub Desktop](appendix-h-github-desktop.md) | [Appendix I: GitHub CLI](appendix-i-github-cli.md) | [Appendix J: Codespaces](appendix-j-cloud-editors.md)* + diff --git a/admin/qa-bundle/docs/02-understanding-github.md b/admin/qa-bundle/docs/02-understanding-github.md new file mode 100644 index 0000000..d5b1a9e --- /dev/null +++ b/admin/qa-bundle/docs/02-understanding-github.md @@ -0,0 +1,657 @@ +# Understanding GitHub's Web Structure +> +> **Listen to Episode 2:** [Understanding GitHub on the Web](../admin/PODCASTS.md) - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. + +> **Related appendices:** [Appendix A: Glossary](appendix-a-glossary.md) | [Appendix B: Screen Reader Cheat Sheet](appendix-b-screen-reader-cheatsheet.md) +> **Authoritative sources:** [GitHub Docs: About GitHub](https://docs.github.com/en/get-started/start-your-journey/about-github-and-git) | [GitHub Accessibility Documentation](https://accessibility.github.com/documentation) + + +## How GitHub Is Organized, and How to Orient Yourself on Every Page + +> **Read this before navigating GitHub for the first time.** This lesson gives you the mental model that makes every subsequent guide easier. Once you understand how GitHub pages are built - their landmark structure, heading hierarchy, and URL patterns - you will know how to orient yourself on any page you land on, even ones this guide never mentions. + +## Table of Contents + +> **Challenge 1: Find Your Way Around** uses the concepts from this chapter and [Chapter 03](03-navigating-repositories.md) and [Chapter 04](04-the-learning-room.md). Read this chapter first to build the mental model, then navigate repositories with confidence. + +1. [GitHub's Three-Level Structure](#1-githubs-three-level-structure) +2. [What Is Always on Every GitHub Page](#2-what-is-always-on-every-github-page) +3. [How to Tell Where You Are](#3-how-to-tell-where-you-are) +4. [The Five Key Page Types](#4-the-five-key-page-types) +5. [Visual Map of a Repository Page](#5-visual-map-of-a-repository-page) +6. [Screen Reader Orientation Sequence](#6-screen-reader-orientation-sequence) +7. [Landmark Structure by Page Type](#7-landmark-structure-by-page-type) +8. [GitHub's Heading Hierarchy in Practice](#8-githubs-heading-hierarchy-in-practice) +9. [How GitHub's Layout Changes by Viewport](#9-how-githubs-layout-changes-by-viewport) +10. [The Mental Model - Building Your Internal Map](#10-the-mental-model---building-your-internal-map) + + +> **The Capstone Connection:** By the end of tomorrow, you will build your own customized AI Agent. But agents do not have magic portals into your code — they read Issues, they write Pull Requests, and they trigger on Labels. Think of GitHub as the operating system for AI. As you learn these manual features today, you are actually learning how to converse with the agents you will build tomorrow. + +## 1. GitHub's Three-Level Structure + +GitHub is not a single page or a single kind of page. It is three nested levels, and understanding which level you are on changes how you navigate. + +```text + Level 1: Your Account / Profile + github.com/your-username + github.com/settings/... + github.com/notifications + +Level 2: An Organization or User's Space + github.com/microsoft + github.com/community-access + github.com/github + +Level 3: A Repository - where all the work happens + github.com/community-access/accessibility-agents + github.com/community-access/accessibility-agents/issues + github.com/community-access/accessibility-agents/pull/42 +``` + +**Most of this workshop happens at Level 3.** Issues, pull requests, code, and actions all live inside a repository. When someone says "go to the repo," they mean Level 3. + +> **Screen reader orientation tip:** The first heading (`H` then `1`) on any page tells you what level you are on. On a repository page, it reads "owner/repo-name." On your profile page, it reads your username. On a settings page, it reads the settings category name. + +## 2. What Is Always on Every GitHub Page + +No matter where you navigate on GitHub, the same global navigation bar is at the top of every page. Understanding its landmark structure means you always have a fixed orientation point. + +### The Global Navigation Bar (always present) + +Visually, the top bar contains (left to right): + +| Element | What It Is | How to Reach It | +| --- | --- | --- | +| GitHub logo / home link | Returns to your personal feed | First link in "Navigation Menu" landmark | +| Search bar | Global search across all of GitHub | `S` or `/` shortcut; or `D` → Navigation Menu → `K` to search | +| Copilot icon | Quick access to GitHub Copilot chat | `K` navigation from search bar | +| Pull Requests | Your PRs across all repos | `K` navigation | +| Issues | Your issues across all repos | `K` navigation | +| Notifications (bell) | Your notification inbox | `G` then `N` shortcut | +| Profile avatar | Account menu, settings, sign out | `K` to last link in nav; or go directly via URL | + +**Screen reader landmark:** All of these live inside the landmark labeled **"Navigation Menu"**. Press `D` to cycle landmarks until you hear "Navigation Menu," then press `K` to move through the links inside it. + +> **Important:** These are standard anchor links. You do not need to switch to Focus Mode to activate them. Press `Enter` in Browse Mode and they work. + +### Secondary navigation (repository pages only) + +When you are inside a repository, a second navigation bar appears below the global bar. This contains the repository's tabs: Code, Issues, Pull requests, Actions, Projects, Wiki, Security, Insights, and Settings. + +**Screen reader landmark:** This is labeled **"Repository navigation"**. Press `D` to jump to it directly. + +### Learning Cards: What Is Always on Every GitHub Page + +
    +Screen reader users + +- Press `D` to cycle landmarks; the first landmark on every page is "Navigation Menu" -- this is your fixed anchor point +- Press `G` then `N` (two keystrokes in sequence) to jump directly to Notifications from any GitHub page +- The global search field is reachable with `S` or `/`; after searching, results load into the Main landmark -- press `D` to jump there + +
    + +
    +Low vision users + +- The global navigation bar is pinned to the top of every page; at 200%+ zoom it may shrink icons but keeps all items in a single row +- The notification bell shows an unread count as a blue dot (or a number badge); zoom in on the top-right corner to see it clearly +- Repository tabs below the global bar highlight the active tab with a colored underline; switch to a high-contrast theme if the underline is hard to see + +
    + +
    +Sighted users + +- The global nav bar runs across the top: GitHub logo (left), search bar (center), and profile avatar/bell icon (right) +- Inside a repository, a second row of tabs (Code, Issues, Pull requests, etc.) appears below the global bar; the active tab has a bold underline +- The notification bell icon in the top-right shows a blue dot when you have unread notifications + +
    + + +## 3. How to Tell Where You Are + +Three signals tell you exactly where you are on GitHub, without needing to see the visual layout: + +### Signal 1: The URL + +GitHub URLs are readable descriptions of your location: + +| URL pattern | Where you are | +| --- | --- | +| `github.com` | Your personal feed / home | +| `github.com/username` | A user profile page | +| `github.com/org` | An organization profile | +| `github.com/owner/repo` | Repository home page (Code tab) | +| `github.com/owner/repo/issues` | Issues list | +| `github.com/owner/repo/issues/42` | A specific issue (number 42) | +| `github.com/owner/repo/pull/7` | A specific pull request (number 7) | +| `github.com/owner/repo/tree/main/docs` | A folder inside the repo | +| `github.com/owner/repo/blob/main/README.md` | A specific file | +| `github.com/owner/repo/commit/a1b2c3d` | A specific commit | +| `github.com/settings/accessibility` | Your accessibility settings | +| `github.com/notifications` | Your notification inbox | + +**Screen reader tip:** Your browser's address bar is always reachable with `Alt+D` (Windows) or `Cmd+L` (Mac). Press it, listen to the URL, and you will know exactly where you are. + +### Signal 2: The browser tab title + +GitHub formats page titles consistently: + +| Page type | Title format | +| --- | --- | +| Repository home | `owner/repo: Short description - GitHub` | +| Issues list | `Issues · owner/repo` | +| Specific issue | `Issue title · Issue #42 · owner/repo` | +| Pull request | `PR title · Pull Request #7 · owner/repo` | +| Your notifications | `Notifications - GitHub` | +| Settings | `Category - Settings` | + +### Signal 3: The first H1 heading + +Press `1` (in Browse Mode) on any GitHub page to jump to the first H1 heading. What you hear tells you what type of page you are on: + +| You hear | You are on | +| --- | --- | +| `owner/repo-name` | Repository home page | +| `Issues` | Issues list | +| The issue title | Issue detail page | +| The PR title | Pull request detail page | +| Your username | Your profile page | +| A settings category name | A settings page | + + +## 4. The Five Key Page Types + +### Page Type 1: Repository Home (Code Tab) + +This is the central hub of any project. It is where you find the file tree, the README, branch information, and links to all other parts of the repository. + +#### What to expect + +- H1: `owner/repo-name` +- Repository navigation landmark (Code, Issues, PRs, Actions tabs) +- A file tree table - navigate with `T` then `Ctrl+Alt+Arrow` +- A rendered README below the file tree +- A sidebar with About, Topics, Releases, Contributors + +### Page Type 2: Issues List + +A searchable, filterable list of all issues in the repository. + +#### What to expect + +- H1: `Issues` +- A search and filter bar at the top +- Each issue is a link with: issue title, labels, number, author, comment count +- Issue titles are H3 headings - press `3` to jump between them +- Landmark: "Search Results List" + +### Page Type 3: Issue Detail + +The full view of a single issue: the original report, all comments, labels, assignees, and the timeline. + +#### What to expect + +- H1: The issue title +- H2: "Description" (original issue body) +- H2: "Activity" (comments and events) +- Landmark: "Add a comment" (the reply box at the bottom) +- Sidebar: assignees, labels, milestone, linked PRs + +### Page Type 4: Pull Request Detail + +The most complex page on GitHub - it has three tabs (Conversation, Commits, Files Changed), each with its own structure. + +#### What to expect + +- H1: The PR title +- Landmark: "Pull request tabs" (Conversation, Commits, Files changed) +- Conversation tab: same structure as an issue detail +- Files Changed tab: a file tree on the left + diff view on the right +- Landmark: "Pull request navigation tabs" - use `D` to reach it, then `Left`/`Right Arrow` to switch tabs + +### Page Type 5: Your Personal Feed and Profile + +Your personal home (`github.com`) shows activity from repositories you follow. Your profile (`github.com/username`) shows your contribution graph, pinned repos, and bio. + +#### What to expect on your feed + +- A "For you" activity stream - recent activity from repos you watch +- A sidebar of suggested repositories and topics + +#### What to expect on your profile + +- H1: Your username +- A contribution activity graph (visually prominent; read as a table by screen readers) +- Pinned repositories +- A list of your recent public activity + +### Learning Cards: The Five Key Page Types + +
    +Screen reader users + +- On the Repository Home page, press `T` to jump to the file table, then `Ctrl+Alt+Down Arrow` to walk through files row by row +- On an Issue Detail page, press `3` to jump between H3 comment headers; each announces the author and timestamp +- On the PR Files Changed tab, press `3` to jump between file name headings; press `4` to jump between diff hunk headers inside each file + +
    + +
    +Low vision users + +- On the Repository Home page, the file tree uses alternating row shading; enable a high-contrast theme if rows blend together +- Issue labels appear as small colored badges next to each title in the Issues list; zoom to 150%+ so the label text is readable +- On the PR Files Changed tab, additions are shaded green and deletions are shaded red; high-contrast themes use bolder shading + +
    + +
    +Sighted users + +- The Repository Home page has a two-column layout: file tree on the left, About sidebar on the right, and README rendered below both +- The Issues list shows a green "Open" or red "Closed" icon next to each issue title, plus label badges and comment count icons +- Pull request tabs (Conversation, Commits, Files changed) appear as a horizontal bar just below the PR title + +
    + + +## 5. Visual Map of a Repository Page + +> **See also:** [Appendix A: Glossary](appendix-a-glossary.md) defines every term used in this course. [Appendix B: Screen Reader Cheat Sheet](appendix-b-screen-reader-cheatsheet.md) has quick-reference keyboard shortcuts for navigating headings and landmarks. + +### Description + +A repository home page is laid out from top to bottom as follows. The Global Navigation bar (landmark: "Navigation Menu") contains the GitHub logo, Search, Copilot, Pull Requests, Issues, Notifications bell, and your avatar. Below that are the Repository Tabs (landmark: "Repository navigation") showing Code, Issues (12), Pull requests (3), Actions, and more. Next is the Repository Header, which is the H1 heading "owner / repo-name" plus Star (42), Watch, and Fork (8) buttons. The main content area is split into two columns. On the left is the File Area with the branch selector (main), Go to file button, Code button, and the File Table (a landmark) listing files like .github/, docs/, and README.md with dates. On the right is the Sidebar with the About section, description text, topics (accessibility), Releases (3), Contributors (5), and Languages (Markdown 100%). Below both columns is the rendered README (landmark: "Repository files navigation"), and at the bottom is the Footer. + +### Screen reader navigation of this page + +Press 1 to hear "owner/repo-name" (the H1, confirms you are on the right repo). Press D to hear "Navigation Menu," then D again for "Repository navigation," then D again for "Main" (the file tree area). Press T to jump to the file table, then Ctrl+Alt+Down Arrow to navigate rows. Press D again to reach "Repository files navigation" and read the README. + + +## 6. Screen Reader Orientation Sequence + +Do this every time you land on a new GitHub page. It takes about 10 seconds once you are practiced. Make it automatic. + +
    +Visual / mouse users - page orientation + +When you land on a GitHub page, scan these areas to orient yourself: + +1. **Browser tab title** - tells you the page type and repo context +2. **Global nav bar** (top strip) - GitHub logo, search box, bells/icons +3. **Repo tabs** (below global nav, visible only inside a repo) - Code, Issues, Pull Requests, etc. +4. **H1 heading** - tells you exactly what page you're on (repo name / "Issues" / issue title / PR title) +5. **Main content area** - file tree, issue list, PR diff, etc. + +That's your visual map. Click anything visible to navigate. + +
    + +
    +Screen reader users (NVDA / JAWS) - 10-second orientation sequence + +```text +Step 1: Press 1 + → Hear: what page type are you on? (repo name / "Issues" / issue title / PR title) + +Step 2: Press D repeatedly + → Hear: what landmark regions exist on this page? + → Build a map: "Navigation Menu, Repository navigation, Main, Add a comment, Pagination" + +Step 3: Press NVDA+F7 (NVDA) or Insert+F3 (JAWS) + → Open the Elements List → choose "Headings" tab + → Hear: the full heading outline of the page + → This tells you every major section available +``` + +After these three steps, you know: + +- **What** page you are on (step 1) +- **Where** the page regions are (step 2) +- **What** content is available and how it is organized (step 3) + +From there, navigate with purpose: `D` to jump to regions, `H` or `3` to jump to content headings, `K` for links, `B` for buttons. + +
    + +
    +Screen reader users (VoiceOver - macOS) - 10-second orientation sequence + +```text +Step 1: Quick Nav H (with Quick Nav on) or VO+Cmd+H → navigate to h1 + → Hear: what page type are you on? (repo name / "Issues" / issue title / PR title) + +Step 2: VO+U → press Left/Right Arrow to choose "Landmarks" → Up/Down to explore + → Build a map: "Navigation Menu, Repository navigation, Main, Add a comment, Pagination" + → Escape to dismiss the rotor + +Step 3: VO+U → press Left/Right Arrow to choose "Headings" + → Hear: the full heading outline of the page + → Up/Down to navigate headings; Enter to jump to one +``` + +After these three steps, you know: + +- **What** page you are on (step 1) +- **Where** the page regions are (step 2) +- **What** content is available and how it is organized (step 3) + +From there, navigate with purpose: `VO+U → Landmarks` to jump to regions, Quick Nav `H` to jump to content headings, Quick Nav `K` for links, Quick Nav `B` for buttons. + +> **VoiceOver tip:** `VO` = `Control+Option`. Turn Quick Nav on/off by pressing `Left Arrow + Right Arrow` simultaneously. Quick Nav lets you use single keys (`H`, `B`, `K`, `T`) without holding `VO`, matching the feel of NVDA/JAWS browse mode. + +
    + +### Learning Cards: Screen Reader Orientation Sequence + +
    +Screen reader users + +- Make the three-step sequence automatic: `1` (hear H1), `D D D` (hear landmarks), `NVDA+F7` or `Insert+F3` (see headings list) +- VoiceOver users: `VO+U` then arrow to "Landmarks" replaces the `D` key; `VO+U` then arrow to "Headings" replaces `NVDA+F7` +- If pressing `1` reads something unexpected, you may be inside a modal or dialog; press `Escape` first, then try `1` again + +
    + +
    +Low vision users + +- Use the browser tab title as a quick orientation check without scrolling; it always shows the page type and repository context +- Press `Alt+D` (Windows) or `Cmd+L` (macOS) to jump to the address bar and read the URL for exact location context +- When disoriented, press `Home` to scroll to the top of the page where the repository name and tabs are always visible + +
    + +
    +Sighted users + +- The H1 heading is visually the largest text near the top of the page, just below the repository tabs +- Landmarks correspond to visual regions you can already see: nav bar at top, tabs below it, main content area, and comment box at bottom +- The Elements List (NVDA+F7) is also useful for sighted users to get a structured outline of any complex page quickly + +
    + + +## 7. Landmark Structure by Page Type + +Each GitHub page type has a consistent landmark pattern. Knowing the pattern means you can skip steps 2 and 3 above for familiar pages. + +> **Landmark navigation quick reference:** +> +> - **NVDA / JAWS:** Press `D` to cycle through landmarks, `Shift+D` to go backwards +> - **VoiceOver (macOS):** Press `VO+U`, then Left/Right to select "Landmarks", then Up/Down to navigate + +### Repository home page landmarks (in order) + +| Landmark (what you hear with `D`) | Contains | +| --- | --- | +| Navigation Menu | Global nav bar - logo, search, PRs, Issues, notifications, avatar | +| Repository navigation | Code, Issues, PRs, Actions, etc. tabs | +| Main | Everything below the tabs - file tree, README | +| Repository files navigation | The rendered README specifically | + +### Issues list page landmarks + +| Landmark | Contains | +| --- | --- | +| Navigation Menu | Global nav | +| Repository navigation | Repo tabs | +| Main | Filter bar + issue list | +| Search Results List | The actual list of issues | +| Pagination | Next/previous page buttons | + +### Issue detail page landmarks + +| Landmark | Contains | +| --- | --- | +| Navigation Menu | Global nav | +| Repository navigation | Repo tabs | +| Main | Issue title, description, comments, sidebar | +| Add a comment | The reply text area and Submit button | + +### Pull request Conversation tab landmarks + +| Landmark | Contains | +| --- | --- | +| Navigation Menu | Global nav | +| Repository navigation | Repo tabs | +| Pull request tabs | Conversation, Commits, Files changed tab links | +| Main | PR description, review threads, merge section | +| Add a comment | The reply box | + +### Pull request Files Changed tab landmarks + +| Landmark | Contains | +| --- | --- | +| Navigation Menu | Global nav | +| Pull request tabs | Tab links | +| Main | File tree + diff view | +| (no "Add a comment" - inline commenting works differently) | - | + + +## 8. GitHub's Heading Hierarchy in Practice + +GitHub uses a predictable heading structure. Learning this pattern means you can navigate any page by heading level alone. + +### Repository home + +```text +H1: owner/repo-name + H2: About (sidebar section) + H2: Releases + H2: (README sections - whatever the author wrote) +``` + +### Issues list + +```text +H1: Issues + (no H2s - issues are listed as links, not headings) + (use I for list items, or 3 for issue headings in some views) +``` + +### Issue detail + +```text +H1: Issue title + H2: Description + H2: Activity + H3: Each comment header (author + timestamp) +``` + +### Pull request detail - Conversation tab + +```text +H1: PR title + H2: (description, if any) + H2: Activity + H3: Each comment header + H3: Each review submission + H4: Each inline comment within a review +``` + +### Pull request detail - Files Changed tab + +```text +H1: PR title + H2: File tree (with "New Files Changed Experience" enabled) + H3: Each file name heading + H4: Each diff hunk heading +``` + +> **Why this matters:** Pressing `3` on a PR Files Changed tab jumps between file headings - this is how you quickly navigate to a specific file without tabbing through the entire diff. + +### Learning Cards: GitHub's Heading Hierarchy + +
    +Screen reader users + +- Press `1` for H1 (page identity), `2` for H2 (major sections), `3` for H3 (individual items like comments, files, or issues) +- On the PR Files Changed tab, `3` jumps between file headings and `4` jumps between diff hunks within each file +- Open the heading list (`NVDA+F7` or `Insert+F3`) and use it as a table of contents to jump directly to any section + +
    + +
    +Low vision users + +- H1 headings on GitHub are displayed in large bold text near the top center of the page; H2 headings use slightly smaller bold text with a horizontal rule above them +- Issue comments (H3) each have a header bar with the author's avatar, name, and timestamp; zoom in on this bar to orient yourself in long discussions +- On the Files Changed tab, each file heading (H3) shows the file path in monospace text with a green/red summary of lines added/removed + +
    + +
    +Sighted users + +- GitHub's heading hierarchy maps to visual size: H1 is the page title, H2 are section dividers, H3 are individual items within sections +- In the Issues list, issue titles function as H3 headings; scan visually or use `3` to jump between them +- On PR conversations, review comments appear in indented boxes; each box header corresponds to an H3 or H4 heading + +
    + + +## 9. How GitHub's Layout Changes by Viewport + +GitHub is a responsive web application. The layout shifts at different screen widths, and this affects what landmarks and headings you encounter. + +### At full desktop width (1200px+) + +- File tree and sidebar are visible alongside the main content +- The full repository tab bar is visible +- All landmark regions described above are present + +### At tablet width (768-1199px) + +- Sidebar may collapse or move below the main content +- Some navigation items may move into a "More" dropdown +- Landmark structure remains the same - only visual position changes + +### At mobile width (below 768px) + +- Global navigation collapses to a hamburger-style menu +- Tabs may scroll horizontally or collapse +- The landmark structure is the same but the "Navigation Menu" landmark becomes a toggle + +**Consistent experience recommendation:** Use your browser maximized or at full desktop width during this workshop. GitHub's landmark and heading structure is most consistent at desktop width. If you hear different landmarks or headings than described in this guide, maximize your browser window. + + +## 10. The Mental Model - Building Your Internal Map + +After your first day of using GitHub, you will have an internal map. Here is what that map should look like: + +```text +GitHub as a building: + +LOBBY (global nav bar) + Always here, same on every floor + Contains: search, your inbox, your identity + Landmark: "Navigation Menu" + +FLOOR SELECTOR (repository nav tabs) + Changes based on which repo you're in + Contains: Code, Issues, PRs, Actions, Settings + Landmark: "Repository navigation" + +MAIN ROOM (the primary content area) + Changes completely depending on which floor you're on + Landmark: "Main" + +MAILBOX (Add a comment) + At the bottom of Issues and PR Conversation pages + Landmark: "Add a comment" + +ELEVATOR BUTTONS (keyboard shortcuts) + G+I = Issues floor + G+P = Pull requests floor + G+C = Code floor + G+A = Actions floor + ? = Show all buttons in this building +``` + +When you get disoriented: + +1. Press `1` - hear the H1 - know what floor you are on +2. Press `D` - hear the landmarks - know what rooms are available +3. Press `NVDA+F7` - see the full outline - know what's in the room + +You are never lost. You always have these three fallbacks. + +### Learning Cards: Building Your Internal Map + +
    +Screen reader users + +- Memorize the elevator shortcuts: `G I` (Issues), `G P` (Pull Requests), `G C` (Code), `G A` (Actions); press `?` on any page to see the full list +- The "Add a comment" landmark is always at the bottom of Issue and PR Conversation pages; press `D` repeatedly until you hear it to jump directly to the reply box +- If a page feels unfamiliar, fall back to the three-step sequence: `1`, `D`, `NVDA+F7` and you will re-orient within seconds + +
    + +
    +Low vision users + +- Think of GitHub like a building: the top bar (lobby) never changes, the tabs below it (floor selector) change per repo, and the main area (room) changes per page +- When disoriented at high zoom, press `Home` to return to the top of the page where the navigation bar and repo tabs are always visible +- The comment box ("mailbox") at the bottom of issue and PR pages has a distinct white input area with a green "Comment" button on its right + +
    + +
    +Sighted users + +- The mental map is: top bar (always there), repo tabs (one row below), then main content; every GitHub page follows this three-layer stack +- Press `?` on any page to see a popup listing all keyboard shortcuts available on that specific page +- The comment box at the bottom of issues and PRs has a tabbed interface (Write/Preview) and a green Submit button; it is always the last section on the page + +
    + + +## Try It: The 60-Second Orientation + +**Time:** 1 minute | **What you need:** A browser with your screen reader running + +Open any GitHub repository - try [github.com/community-access/accessibility-agents](https://github.com/community-access/accessibility-agents) - and prove to yourself that the mental model works: + +1. Press `1` - your screen reader announces the repo name. You know where you are. +2. Press `D` - you hear the first landmark. Press `D` again to hear the next one. You now know the rooms on this floor. +3. Press `2` - you jump to the first section heading. Press `2` again to scan the page structure. +4. Press `H` three times - you're moving through headings at any level. You're reading the outline. + +**You're done.** Four keys, under a minute. You just navigated a GitHub repository by ear. + +> **What success feels like:** You heard a repo name, at least two landmarks, and several headings. If you did, you can orient yourself on *any* GitHub page using these same four keys. + + +## If You Get Stuck + +| Problem | What to do | +|---|---| +| Screen reader says nothing when pressing `1` | Ensure browse mode is active (NVDA: press `Escape`; JAWS: press `Num Pad Plus`). GitHub pages must fully load before heading navigation works. | +| Landmarks announce differently than expected | GitHub updates its landmark structure periodically. Press `D` to cycle landmarks and listen to what is announced rather than expecting exact names. | +| Page seems empty or broken | Some GitHub features require JavaScript. Ensure your browser has JavaScript enabled and try refreshing with `Ctrl+Shift+R`. | +| Cannot find the repository navigation tabs | Press `D` until you hear "Repository navigation" then press `K` or `Tab` to find Code, Issues, Pull Requests tabs. | +| Everything else | Post a comment on your challenge issue describing what you see and hear. A facilitator or buddy can walk you through it. | +| I finished but I am not sure I did it right | Compare your work against the [Challenge 1 reference solution](solutions/solution-01-scavenger-hunt.md). Your version does not need to match exactly -- if you explored the tabs and found the key files, you succeeded. | + + +## Day 2 Amplifier + +> Once you have this mental model solid, the Accessibility Agents make more sense. The `@daily-briefing` agent reads your GitHub notifications and presents a structured report - but the report structure mirrors the landmark structure of GitHub itself: global activity, then per-repo activity, then per-issue and per-PR detail. The agent describes the same building you have already walked through manually. + + +> **Next Step:** Move on to [Chapter 03: Navigating Repositories](03-navigating-repositories.md). + +--- + + +*Next: [Chapter 03: Navigating Repositories](03-navigating-repositories.md)* +*Back: [Chapter 01: Choose Your Tools](01-choose-your-tools.md)* +*Related appendices: [Appendix A: Glossary](appendix-a-glossary.md) | [Appendix B: Screen Reader Cheat Sheet](appendix-b-screen-reader-cheatsheet.md)* + + + diff --git a/admin/qa-bundle/docs/03-navigating-repositories.md b/admin/qa-bundle/docs/03-navigating-repositories.md new file mode 100644 index 0000000..1272f85 --- /dev/null +++ b/admin/qa-bundle/docs/03-navigating-repositories.md @@ -0,0 +1,851 @@ +# Navigating Repositories +> +> **Listen to Episode 3:** [Navigating Repositories](../admin/PODCASTS.md) - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. + +> **Related appendices:** [Appendix A: Glossary](appendix-a-glossary.md) | [Appendix B: Screen Reader Cheat Sheet](appendix-b-screen-reader-cheatsheet.md) +> **Authoritative sources:** [GitHub Docs: About repositories](https://docs.github.com/en/repositories/creating-and-managing-repositories/about-repositories) | [GitHub Accessibility Guide: Repositories](https://accessibility.github.com/documentation/guide/repos/) + + +## A Screen Reader Guide to GitHub Repositories + +> This guide covers everything you need to explore a GitHub repository using your keyboard and screen reader. No mouse required. + +> **Official GitHub Accessibility Guide:** GitHub publishes an NVDA-focused guide for navigating repositories with a screen reader at [Using GitHub Repositories with a Screen Reader](https://accessibility.github.com/documentation/guide/repos/). This chapter covers the same material with additional perspectives (VoiceOver, low vision, CLI) and workshop-specific guidance. Use the official guide as a companion reference. + + +## Workshop Recommendation (Chapter 3) + +Chapter 3 is a **confidence-building orientation chapter**. + +- **Challenge count:** none +- **Automation check:** none +- **Why:** this chapter teaches navigation foundations that are practiced in later issue and PR chapters. + +### Safety-First Learning Pattern + +Use this sequence before moving to graded chapters: + +1. Learn the page structure (heading, landmarks, tabs). +2. Practice orientation (`1`, `D`, heading list). +3. Confirm readiness with a peer or facilitator. +4. Move to Chapter 4 for Learning Room orientation, then Chapter 5 for issue-based, traceable challenges. + + +### About Learning Cards in This Chapter + +This chapter provides learning cards: expandable blocks that offer perspective-specific guidance for different ways of working. Not every card appears at every step. Open the ones that match how you work. + +The following table describes the four learning card types used in this chapter. + +| Card | Who it helps | What it covers | +| --- | --- | --- | +| Visual / mouse | Sighted users navigating with a mouse or trackpad | Click targets, visual cues, layout orientation | +| Low vision | Users with magnification, zoom, or high-contrast themes | Zoom-friendly navigation, locating controls at high magnification | +| Screen reader (NVDA / JAWS) | Screen reader users on Windows | Keystroke sequences, Focus and Browse mode, landmark navigation | +| Screen reader (VoiceOver) | Screen reader users on macOS | VO key sequences, rotor usage, interaction model | + + +## What Is a Repository Page? + +When you navigate to a GitHub repository (e.g., `https://github.com/owner/repo-name`), you land on the **repository home page** (also called the Code tab). This page has several distinct regions: + +### Description + +The repository home page is organized from top to bottom as follows. The Navigation bar (GitHub global nav) contains the avatar menu, Notifications, and search. Below that is the Repository header showing "owner / repo-name" as the H1 heading, plus Star, Watch, and Fork buttons. Next are the Repository navigation tabs (a landmark) with Code (active), Issues, Pull requests, Actions, and more. The main content area is split into two columns: on the left is the File tree / code panel with the branch selector, Files table (navigable as a table), and last commit message; on the right is the Sidebar with the About section, topics, and releases. Below both columns is the rendered README.md in a separate landmark region. + + +## Landing on a Repository - What to Expect + +When you first navigate to a repo URL: + +1. **The page title** is announced with the format: `owner/repo-name: Short description - GitHub` +2. **First heading** (`1` key) will navigate to the repo name: "owner/repo-name" +3. **The tab bar** is a landmark labeled "Repository navigation" + +### Orientation sequence (do this on every new repo) + +```text +Step 1: Press 1 - hear the repo name +Step 2: Press D - navigate through landmarks to learn page structure +Step 3: Press NVDA+F7 (or VO+U) - scan headings to understand what's on the page +``` + +> **Key landmark names you will hear with `D`:** Repository pages have three main landmark sections: **"Repository Navigation"** (the tab bar), **"Main"** (the file tree, branch selector, repo details, and contributors), and **"Repository Files Navigation"** (the rendered README content). Within each landmark, press `H` or `2` to navigate subsections - most are organized under heading level 2. + + +## Navigating the Repository Tabs + +The main tabs are: **Code**, **Issues**, **Pull Requests**, **Discussions**, **Actions**, **Projects**, **Wiki**, **Security**, **Insights**, and **Settings** (Settings only visible to maintainers). Not all tabs appear on every repository - Discussions, Wiki, and Projects must be enabled by the repository owner. + +### How to reach the tabs + +
    +Visual / mouse users + +The tab bar is visible just below the repository name. Click the tab you want - **Code**, **Issues**, **Pull requests**, etc. The active tab is underlined. The number next to a tab (e.g., "Issues · 14") shows how many open items are in that section. + +
    + +
    +Low vision users (zoom, high contrast) + +The tab bar is just below the repository name. At 200% browser zoom or higher: + +- The tabs may wrap to two lines. Each tab remains a standard link. +- The active tab is indicated by an underline. In Windows High Contrast mode, the underline uses the system accent color. +- Tab counts ("Issues · 14") appear as part of each tab's text and remain readable at high magnification. +- If tabs are hard to click at high zoom, press `Tab` from the repo heading to cycle through each tab link sequentially. +- **Keyboard shortcut:** Press `G` then `I` to jump directly to Issues, or `G` then `P` for Pull requests. These two-key shortcuts work from any page in the repository. + +
    + +
    +Screen reader users (NVDA / JAWS) + +1. Press `D` to jump to the **"Repository navigation"** landmark +2. Press `K` or `Tab` to navigate between the tab links + +
    + +
    +Screen reader users (VoiceOver) + +1. `VO+U` → Landmarks rotor → navigate to **"Repository navigation"** +2. `VO+Right` to move through items in the landmark + +
    + +### Reading the tab labels + +Each tab link reads with its name and the count of items: "Issues, 14 open" or "Pull requests, 3 open." The active tab is marked with `aria-selected="true"` - your screen reader will announce it as "selected" or "current." + + +## The Files Table + +> **See also:** [Appendix B: Screen Reader Cheat Sheet](appendix-b-screen-reader-cheatsheet.md) lists the keyboard shortcuts for navigating repository file trees. + +The files table is the core of the Code tab - it shows every file and folder in the repo. + +### Reaching the files table + +
    +Visual / mouse users + +The file table is the main panel of the Code tab, showing folders and files with their most recent commit message and how long ago each was changed. It’s visible immediately below the branch selector. Click any folder name to open it, or click a file name to view the file. + +
    + +
    Low vision users (zoom, high contrast) + +The file table occupies the main content area of the Code tab. At high magnification: + +- The table has three columns: Name, Message (last commit), and Date. At 200%+ zoom, the Message and Date columns may be truncated. Hover over truncated text to see the full message in a tooltip. +- Folder icons appear before folder names; file icons appear before file names. In Windows High Contrast mode, these icons use system colors with visible outlines. +- Click any folder or file name to navigate into it. The names are standard links with hover underlines. +- Use `Ctrl+F` (browser Find) to search for a specific file name rather than scrolling a long file list at high zoom. +- The **Go to file** button (`T` keyboard shortcut) opens a search-as-you-type file finder. This is the fastest way to navigate to a specific file at any zoom level. + +
    + +
    Screen reader users + +Press `T` to jump to the next table on the page. The first table you will hit is usually the files table. NVDA will announce: “Table with [N] rows and 3 columns.” + +
    + +The three columns are: + +1. **Name** - file or folder name +2. **Message** - the most recent commit message that changed this file +3. **Age** - how long ago that commit happened + +### Navigating the files table + +| Goal | Keys (NVDA/JAWS) | Keys (VoiceOver) | +| ------ | ----------------- | ----------------- | +| Move down one row (next file) | `Ctrl+Alt+↓` | `VO+Shift+↓` | +| Move up one row | `Ctrl+Alt+↑` | `VO+Shift+↑` | +| Move right one column | `Ctrl+Alt+→` | `VO+Shift+→` | +| Move left one column | `Ctrl+Alt+←` | `VO+Shift+←` | +| Open a file or folder | `Enter` (on the Name column) | `VO+Space` | + +#### Reading a row + +Navigate to the Name column, hear the filename, then move right to read the commit message, then right again for the age. For example: "docs/ | Add accessibility guide | 3 days ago" + +### Folder vs file + +- Folders end with a `/` in the Name column +- When you open a folder, the page reloads showing the contents of that folder +- Press the back button or use the breadcrumb links to go back up + +### Learning Cards: The Files Table + +
    +Screen reader users + +- Press `T` in Browse Mode to jump to the files table; NVDA announces "Table with N rows and 3 columns" +- Navigate rows with `Ctrl+Alt+Down Arrow`; each row reads: filename, last commit message, age +- Press `Enter` on the Name column to open a file or folder; press `Alt+Left Arrow` in your browser to go back + +
    + +
    +Low vision users + +- The files table uses alternating row shading; switch to a high-contrast GitHub theme if rows blend together at your zoom level +- Folder icons (small triangle) appear before folder names; file icons (small document) appear before file names +- If the commit message column is truncated at high zoom, hover over it to see the full message in a tooltip + +
    + +
    +Sighted users + +- The files table is the large panel in the center of the Code tab, listing folders first (alphabetically), then files +- The rightmost column shows relative timestamps like "3 days ago"; hover to see the exact date and time +- Click a folder name to drill into it; breadcrumb links above the table let you navigate back up the path + +
    + + +## The Branch Selector + +The branch selector button sits just above the files table. It lets you switch which branch you are viewing. + +### How to open the branch selector + +
    +Visual / mouse users + +Mouse users see the current branch name as a button with a dropdown arrow (e.g., `main ▼`) just above the file table. Click it to open the branch list. Type to filter branches, then click a branch name to switch. + +
    + +
    +Low vision users (zoom, high contrast) + +The branch selector button shows the current branch name (e.g., "main") with a dropdown arrow. It sits just above the file table. + +- At high magnification, the button may wrap next to other controls. It is a standard button with visible border and text. +- Click it to open a dropdown with a search field and branch list. Type part of a branch name to filter the list. +- In the dropdown, branch names can be long. At high zoom, they may truncate. Hover for the full name. +- In Windows High Contrast mode, the currently active branch is highlighted with the system selection color. +- **Alternative:** Press `W` to open the branch/tag picker directly from the keyboard. This avoids needing to find and click the button. + +
    + +
    +Screen reader users (NVDA / JAWS) + +1. After reaching the repository navigation landmark, press `B` to navigate to buttons +2. The branch button reads: “[branch-name] branch” (e.g., “main branch”) +3. Press `Enter` to open the dropdown + +
    + +
    +Screen reader users (VoiceOver) + +1. `Tab` to the branch button (it will be labeled with the current branch name) +2. `VO+Space` to open + +
    + +### Inside the branch dropdown + +```text +Step 1: The dropdown panel opens - it is a live region +Step 2: A search field appears - you can type to filter branches +Step 3: Press Tab to move to the results list +Step 4: Press ↓/↑ or Tab/Shift+Tab to navigate the list of branches +Step 5: Press Enter to switch to the selected branch +Step 6: Press Escape to close without switching +``` + +To return to the search field from the list: navigate to the tabs control at the top of the dropdown ("Branches" and "Tags" tabs), then use `Shift+Tab`. + +**VoiceOver:** After activating the button, `VO+Down` to interact with the dropdown → `VO+Right` to navigate items. + +### Switching to a tag + +Tags mark specific releases or versions. The branch dropdown also provides tag navigation: + +1. Open the branch button (same steps as above) +2. Inside the dropdown, navigate to the **tabs control** at the top (reads as "Branches tab" and "Tags tab") +3. Use `←/→` to switch to the **Tags** tab +4. `Tab` to move to the tags list +5. Navigate with `↑/↓` and press `Enter` to select a tag + +The repository page reloads showing the code at that tagged version. + + +## Cloning a Repository + +Cloning copies the repository to your local machine so you can work with it in VS Code or the terminal. + +
    +Visual / mouse users + +1. On the repository’s main page (Code tab), find and click the green **Code** button above the file table +2. A popover opens showing **HTTPS**, **SSH**, and **GitHub CLI** tabs +3. Click the **HTTPS** tab (default) and click the **copy** icon next to the URL +4. Open your terminal, `cd` to where you want the folder, and run `git clone ` +5. Alternatively, click **Download ZIP** to get a one-time archive without Git + +
    + +
    +Screen reader users + +1. Press `1` or `Shift+1` to navigate to the repository h1 heading +2. Press `B` to navigate to the next button - look for the **“Code”** button +3. Press `Enter` or `Space` to open the Code flyout panel +4. The flyout has tabs: **HTTPS**, **SSH**, **GitHub CLI** +5. `Tab` to the HTTPS tab or SSH tab according to your preference +6. `Tab` to the “Copy url to clipboard” button and press `Enter` +7. The URL is now in your clipboard - paste it into VS Code or your terminal + +**Alternative:** `Tab` further to find **Download ZIP** if you want a one-time copy without Git. + +> **VoiceOver:** After activating the Code button, interact with the flyout panel with `VO+Shift+Down`. Use `VO+Right` to move to HTTPS/SSH tabs and `VO+Space` to select. + +
    + +
    +GitHub CLI (gh) alternative + +Clone a repository with one command using the GitHub CLI: + +```bash +# Clone using the repo's owner/name (no URL needed) +gh repo clone community-access/git-going-with-github + +# Clone and cd into the folder +gh repo clone community-access/git-going-with-github && cd git-going-with-github +``` + +## Or with standard Git + +```bash +git clone https://github.com/community-access/git-going-with-github.git +cd git-going-with-github +``` + +**Setup:** Install the GitHub CLI from [cli.github.com](https://cli.github.com) and authenticate with `gh auth login`. See [Appendix D](appendix-d-git-authentication.md) for details. + +
    + +### Learning Cards: Cloning a Repository + +
    +Screen reader users + +- Navigate to the green "Code" button with `B` (Browse Mode), press `Enter` to open the flyout, then `Tab` to reach the HTTPS URL and the "Copy url to clipboard" button +- After cloning in VS Code's terminal, press `Ctrl+Shift+E` to focus the Explorer panel; the cloned repository's file tree appears there +- If the clone fails with an authentication error, VS Code will open a browser tab for OAuth sign-in; press `Alt+Tab` to switch back after approving + +
    + +
    +Low vision users + +- The green "Code" button is above the file table on the right side; at high zoom it may shift below the branch selector +- The clone URL in the flyout panel uses small monospace text; use the copy button (clipboard icon) instead of trying to select the text manually +- After cloning, VS Code's Explorer panel shows the folder tree on the left; zoom VS Code independently with `Ctrl+=` if needed + +
    + +
    +Sighted users + +- The green "Code" dropdown shows three tabs: HTTPS (default), SSH, and GitHub CLI, each with a one-click copy button +- After cloning, look for a notification in VS Code's bottom-right corner asking "Would you like to open the cloned repository?"; click "Open" +- The Source Control icon in VS Code's Activity Bar shows a badge number when there are uncommitted changes in your clone + +
    + +### Tool Cards: Clone a Repository + +**github.com (browser):** +1. Click the green **Code** button above the file table. +2. Copy the HTTPS URL. +3. You will paste this into your local tool of choice below. + +**github.dev (web editor):** +No clone needed. Press `.` on any repository page to open it in the browser-based editor instantly. + +**VS Code Desktop:** +1. Press `Ctrl+Shift+P`, type **Git: Clone**, press `Enter`. +2. Paste the HTTPS URL and choose a local folder. +3. Click **Open** when prompted. + +**GitHub Desktop:** +1. **File > Clone Repository** (or `Ctrl+Shift+O`). +2. Paste the URL or select from your GitHub account list. +3. Choose a local path and click **Clone**. + +**Git CLI (terminal):** +```bash +git clone https://github.com/owner/repo.git +cd repo +``` + + +## Fork vs. Clone vs. Branch - What Is the Difference? + +These three concepts are related but serve different purposes. Students often confuse them, so here is a side-by-side comparison. + +The following table compares forks, clones, and branches across six dimensions. + +| Dimension | Fork | Clone | Branch | +| --- | --- | --- | --- | +| **What it creates** | A new repository on GitHub under your account | A local copy of a repository on your computer | A named pointer to a line of commits within the same repository | +| **Where it lives** | On GitHub (your account) | On your local machine | Inside any repository (local or remote) | +| **Relationship to original** | Linked (GitHub tracks the "parent" repo) | Independent copy (but has `origin` remote pointing to GitHub) | Part of the same repository | +| **When to use it** | Contributing to a repo where you do not have write access (most open source) | Working locally with Git and VS Code | Creating an isolated workspace for a feature, fix, or experiment | +| **How to contribute back** | Open a pull request from your fork to the original (upstream) repo | Push your branch to the remote, then open a PR | Open a pull request from your branch to `main` | +| **Workshop usage** | Not required for the Learning Room (you have direct write access) | Optional in Block 0 (for local Git work in Ch11+) | Required from Chapter 6 onward (feature branches for every PR) | + +**In this workshop,** you will primarily use **branches** (Chapter 6 onward) and optionally **clone** the Learning Room for local work (Chapter 11). Forking is the standard workflow when contributing to repositories where you are not a collaborator, which is covered in [Contributing to Open Source](08-open-source-culture.md). + +### Learning Cards: Fork vs. Clone vs. Branch + +
    +Screen reader users + +- Fork: press `B` to find the "Fork" button on any repo page, then `Enter`; the fork creation page opens with fields for owner and name +- Clone: use the green "Code" button or run `gh repo clone owner/repo` in VS Code's terminal (`` Ctrl+` ``) +- Branch: you will create branches starting in Chapter 6; the branch selector (`W` shortcut in Focus Mode) lists all branches in the current repo + +
    + +
    +Low vision users + +- The Fork button shows a count (e.g., "Fork 8") in the top-right of the repo page near Watch and Star +- After forking, your fork's URL changes to `github.com/your-username/repo-name`; check the address bar to confirm you are on your fork +- Branches are listed in the branch selector dropdown; the currently active branch is highlighted with your theme's selection color + +
    + +
    +Sighted users + +- Fork, Watch, and Star buttons are grouped in the top-right corner of the repository page, right-aligned below the global nav +- A forked repo shows "forked from owner/repo" in small text just below the repository name +- Branches appear in the branch dropdown (click the branch name above the file tree); the default branch is usually labeled "main" or "master" + +
    + + +## Watching, Starring, and Forking + +These three actions let you follow, bookmark, or copy a repository. + +### Watching (subscribe to notifications) + +
    +Visual / mouse users + +The **Watch**, **Star**, and **Fork** buttons are at the top-right of the repository page, just below the global navigation bar. Click **Watch** to open a dropdown of subscription options: **Participating and @mentions**, **All Activity**, or **Ignore**. Select your preference and click **Apply**. + +
    + +
    +Screen reader users + +1. Press `L` to navigate through list items to reach the **Main** landmark +2. Continue pressing `L` until you find the **Watch** button (reads as “Watch this repository”) +3. Press `Enter` to open the subscription submenu +4. Press `↑/↓` to browse options: Participating, All Activity, Ignore, Custom +5. Press `Enter` to confirm +6. If you choose **Custom**, a dialog opens with checkboxes for specific activity types (Issues, Pull requests, Releases, Discussions, Security alerts). Check the boxes you want and activate the **Apply** button. + +
    + +### Forking (create your own copy) + +
    +Visual / mouse users + +Click the **Fork** button (top-right, next to Watch and Star). A page opens asking you to choose the owner and repository name for your fork. Fill in the details and click **Create fork**. + +
    + +
    +Screen reader users + +1. Press `L` to navigate list items in the Main landmark +2. Press `I` to navigate individual list items until you find “Fork your own copy” +3. Press `Enter` to start the fork workflow +4. The fork creation page lets you choose the owner and repository name +5. Tab to “Create fork” and press `Enter` + +
    + +### Starring (bookmarking) + +
    +Visual / mouse users + +Click the **Star** button (top-right). The button changes to **Starred** with a filled star icon to confirm. Click it again to unstar. + +
    + +
    +Screen reader users + +1. Press `L` to navigate list items in the Main landmark +2. Press `I` to navigate individual list items until you find “Star this repository” +3. Press `Enter` or `Space` to star +4. The button text changes to “Unstar” on the next focus + +> **Tip:** If the Watch/Fork/Star area is not immediately found with `L`, press `D` to navigate to the **Main** landmark first, then use `I` to browse list items within that region. + +
    + + +## Viewing a Single File + +When you open a file from the files table, the page shows the rendered content (for Markdown files) or the raw code (for code files). + +### File page landmarks + +```text +D → "Repository navigation" - repo tab bar +D → "Repository header" - file breadcrumb path +D → "Main" - the file content area +D → "Repository files navigation" - contains: Raw, Blame, History buttons +``` + +### Reading a Markdown file (like README.md) + +The README renders with full heading structure. Use: + +- `H` - navigate headings within the README +- `T` - find any tables +- `L` - find lists +- `K` - navigate links + +### Reading a code file + +Code files render as a table where each row is one line of code. Content is read line by line. + +| Goal | Keys | +| ------ | ------ | +| Read the file content | `↓` to read line by line | +| Jump to a specific line | Open Raw view (`R` button), then use browser `Ctrl+F` | +| View in Focus Mode | `NVDA+Space`, then `↓` arrows through lines | + +### The file action buttons + +Above the file content, there are buttons: + +- **Raw** - view the file as plain text in a new page +- **Blame** - see which commit changed each line (see below) +- **History** - see the full commit history for this file +- **Edit (pencil)** - edit the file directly on GitHub (if you have write access or it's your fork) + +#### How to reach these buttons + +Press `B` from within the file area, OR use `D` to navigate to the "Repository files navigation" landmark. + +### Editing a file + +
    +Visual / mouse users + +1. Open the file you want to edit +2. Click the **pencil icon** (Edit file) in the top-right of the file content area +3. The file opens in a web editor - click in the content area and edit +4. When done, scroll down to “Commit changes”, type a commit message, and click the green **Commit changes** button +5. Choose “Commit directly to `main`” (or your branch) and confirm + +
    + +
    +Screen reader users + +1. Open the file you want to edit +2. Press `K` to navigate links until you find the **“Edit file”** link (may be labeled with a pencil icon description) +3. Press `Enter` to activate the link - the page opens in edit mode with a code editor textarea +4. Switch to Focus Mode: press `NVDA+Space` (NVDA) or `Insert+Z` (JAWS) +5. Make your changes using standard text editing keys +6. When done, press `Escape` to exit the textarea +7. Press `Shift+Tab` to navigate backwards to the **“Commit Changes”** button +8. Press `Enter` to open the commit dialog +9. Type your commit message in the dialog, then Tab to the confirm button and press `Enter` + +> **Note:** Switch back to Browse Mode after step 6 (`NVDA+Space`) to use `Shift+Tab` more reliably to reach the commit button. + +
    + +### Learning Cards: Viewing a Single File + +
    +Screen reader users + +- On a Markdown file, the rendered content has full heading structure; press `H` to navigate headings within the file, `T` for tables, `K` for links +- On a code file, content reads as a table with one line per row; press `Down Arrow` in Focus Mode to read line by line +- The action buttons (Raw, Blame, History, Edit) are above the file content; press `B` or navigate to the "Repository files navigation" landmark with `D` to find them + +
    + +
    +Low vision users + +- Markdown files render with styled headings and formatted text; code files render with syntax highlighting in a monospace font +- The Edit button (pencil icon) is in the top-right corner of the file content area; at high zoom it appears above the first line of the file +- Use the Raw button to view files as plain text in a new page, which can be easier to read at high zoom without the GitHub page chrome + +
    + +
    +Sighted users + +- The file action buttons (Raw, Blame, History, pencil icon for Edit) are in a toolbar row above the file content +- Line numbers appear on the left side of code files; click a line number to highlight that line and generate a permalink URL +- The breadcrumb path above the file (e.g., "repo > docs > README.md") is clickable; each segment navigates to that folder level + +
    + + +## The Blame View + +Blame shows you who changed each line of a file, in what commit, and when. It is useful for tracing why a particular change was made. + +### Navigating Blame + +1. From a file page, activate the "Blame" button +2. The page reloads in Blame view +3. The content is a table: **left column** = commit info (who, when, message), **right column** = the line of code + +```text +T - jump to the blame table +Ctrl+Alt+→ - move from commit info column to code column +Ctrl+Alt+↓ - move to the next line +K - navigate the commit links (opens that commit's detail page) +``` + + +## Commit History + +Two ways to view history: + +- **Repo-level history:** On the Code tab, find the "commits" link near the top (it shows a number like "1,234 commits"). Press `K` and navigate links to find it. +- **File-level history:** From any file page, activate the "History" button. + +### Reading the Commits List Page + +```text +H or 3 - navigate by date headings (commits are grouped by date) +I - navigate individual commit list items +K - navigate commit links (SHA hashes, short descriptions) +Enter - open a commit to see its diff +``` + +### Reading a Commit Page + +A commit page shows: + +- The commit message (heading) +- Author and date +- Parent commit link +- A diff for every file changed + +```text +1 - go to commit message heading +H or 3 - navigate file headings in the diff +T - navigate to the stats table (files changed, lines added/deleted) ++ - skip table navigation and read file diffs by line +``` + + +## Searching for a File + +The "Go to file" shortcut is extremely useful when you know what you are looking for. + +### How to use Go to File + +1. Make sure you are on the Code tab of a repository + - If hovercards are off, no navigation penalty - just navigate normally +2. Find the search box: press `F` or `E` to jump to the next edit field - look for one labeled "Go to file" or "Filter files by name" +3. Type the filename or partial path +4. Results appear as a dropdown - use `↓` to navigate, `Enter` to open + +**GitHub keyboard shortcut:** `T` - opens the Go to File dialog. + +**Screen reader conflict warning:** `T` normally means "next table" in NVDA/JAWS Browse Mode. GitHub's `T` shortcut conflicts with this. To use GitHub's `T` shortcut: + +- **Option 1:** Switch to Focus Mode first (`Insert+Space` for NVDA, `Insert+Z` for JAWS) +- **Option 2:** Use `F` key to find the "Go to file" or "Find file" edit field instead +- **Recommended:** Option 2 is more reliable and doesn't require mode switching. + +### Learning Cards: Searching for a File + +
    +Screen reader users + +- Press `F` or `E` in Browse Mode to jump to the "Go to file" search field; type a filename and results appear as a dropdown navigable with `Down Arrow` +- The GitHub `T` shortcut also opens the file finder, but it conflicts with the "next table" key in Browse Mode; switch to Focus Mode first (`NVDA+Space`) or use `F` instead +- After selecting a result and pressing `Enter`, the file page loads; press `1` to hear the file name, then `H` to navigate its headings + +
    + +
    +Low vision users + +- The "Go to file" button is near the top of the Code tab, above the file table; it opens a search overlay in the center of the screen +- Search results highlight matching characters in bold; at high zoom the overlay may cover part of the file table underneath +- Use browser `Ctrl+F` as a fallback to search for a filename visible in the file table without opening the overlay + +
    + +
    +Sighted users + +- The "Go to file" button (or press `T`) opens a search-as-you-type overlay showing matching file paths as you type +- Results show the full file path with matching characters highlighted in bold; press `Enter` on a result to open the file +- Fuzzy matching works: typing "readme" matches "README.md" and "docs/readme.txt" and any other file with those characters in order + +
    + + +## GitHub Shortcuts for Repository Navigation - Spotlight + +These are the GitHub built-in shortcuts you will use most on repository pages. They work by sending keystrokes directly to GitHub's JavaScript, so **enable Focus Mode first** (NVDA: `NVDA+Space`, JAWS: `Insert+Z`). + +| Shortcut | What it does | When you need it | +| --- | --- | --- | +| `?` | Show all shortcuts for this page | Any time - get the full context-specific list | +| `G C` | Jump to the Code tab | You're on Issues or PRs and want the file tree | +| `G I` | Jump to the Issues tab | You're browsing code and spot a bug to report | +| `G P` | Jump to the Pull Requests tab | You want to review open PRs | +| `G A` | Jump to Actions / workflow runs | You want to check CI status | +| `G G` | Jump to Discussions | You want to participate in project conversations | +| `G W` | Jump to Wiki | You want to view the repository wiki | + +**How to use:** Press `G`, release it, then press the second letter. For example: press `G`, release, press `C` (not `G+C` together). +| `.` or `>` | Open repository in github.dev (VS Code in browser) | You want to edit a file or read code with VS Code shortcuts | +| `W` | Switch branch or tag | You want to browse a different branch of the code | +| `Y` | Expand URL to permanent canonical link | You want a link that always points to this exact commit | + +**Press `?` now** on any GitHub repository page to see the live shortcut list for that specific context. + +> **Screen reader tip - reading the shortcut dialog:** When the `?` dialog opens it is a modal overlay. Press `NVDA+Space` (NVDA) or ensure JAWS Virtual Cursor is active to browse the dialog content with `H` for headings and `↓` to read each shortcut. The dialog is **context-aware** - the shortcuts listed change based on the page you are on. Press `Escape` to close. + +For the full shortcut system including issues, PRs, comments, and notifications, see [Screen Reader Cheat Sheet - GitHub Shortcuts section](appendix-b-screen-reader-cheatsheet.md#github-built-in-keyboard-shortcuts). + +The sidebar (on desktop-width windows) contains: + +- **About** - the repo description and topics +- **Releases** - recent published releases +- **Packages** - Docker/npm packages attached to the repo +- **Contributors** - the top contributors +- **Languages** - the percentage breakdown of programming languages + +### Navigating the sidebar + +The sidebar content is inside the "Main" landmark, after the files table and README. After the README, press `H` or `2` to reach "About" and the sidebar section headings. + +**VoiceOver:** Navigate past the README section with `VO+Right` - the sidebar elements follow sequentially in the reading order. + + +## The Repository About Section + +Quick way to check the project description, website link, and topics: + +1. Press `D` to walk through landmarks +2. Look for a heading "About" in the sidebar +3. `2` or `H` to jump to that "About" heading +4. Then `↓` to read the description, URL, and topics + + +## Practical Scenarios + +### Scenario A: "I want to find out what this project does" + +1. Navigate to the repo URL +2. Press `1` - hear the repo name +3. `↓` - read the description (announced as a paragraph after the heading) +4. Navigate to README: `D` → "Repository files navigation" → `H` within the README + +### Scenario B: "I want to find a good file to edit" + +1. Open the files table with `T` +2. Navigate rows with `Ctrl+Alt+↓` +3. Move right with `Ctrl+Alt+→` to read the commit message (what's been changing recently) +4. When found, press `Enter` on the Name column to open the file + +### Scenario C: "I want to know who has been working on this file recently" + +1. Open the file +2. Activate the "Blame" button (`B` from the Repository files navigation landmark) +3. Navigate the blame table to see authors + +### Scenario D: "I want to understand what changed in the last release" + +1. Navigate to the sidebar "Releases" section (`H` or `2`) +2. Activate the latest release link +3. Read the release notes (rendered Markdown with headings and lists) + +### Scenario E: "I want to contribute - where do I start?" + +1. Navigate to the Code tab +2. Look for `CONTRIBUTING.md` in the files table +3. Open it and read the contributing guidelines +4. Then go to Issues tab and filter by `good first issue` + + +## If You Get Stuck + +| Problem | What to do | +|---|---| +| Clone fails with "authentication required" | You need to sign in. See [Appendix D](appendix-d-git-authentication.md) for HTTPS authentication setup. | +| Cannot find the Code button for cloning | Press `B` to cycle buttons. The green "Code" button is above the file table. On narrow screens it may be hidden behind a "..." overflow menu. | +| File finder (`T` shortcut) does not open | Ensure you are in Focus Mode (NVDA: `NVDA+Space`). The `T` shortcut only works in the repository Code tab. | +| Forking creates a repo I did not expect | By default, forking copies only the default branch. Go to your fork's settings if you need to adjust. The original repo is untouched. | +| `G I` or `G P` shortcuts do not work | These require two separate key presses (G, release, then I or P), not simultaneous. Ensure Focus Mode is active first. | +| Everything else | Post a comment on your challenge issue describing what you tried. A facilitator or buddy will help. | + + +## Try It: The Five-Tab Tour + +**Time:** 3 minutes | **What you need:** Browser with screen reader, signed in to GitHub + +Navigate to the [Accessibility Agents repository](https://github.com/community-access/accessibility-agents) and do this: + +1. **Code tab** - Press `D` to the "Repository navigation" landmark, then `K` to find "Code". Press `Enter`. You're on the file list. +2. **Issues tab** - Press `G` then `I` (Focus Mode first: `NVDA+Space`). How many open issues are there? Press `3` to jump through issue titles. +3. **Pull Requests tab** - Press `G` then `P`. Are there any open PRs? +4. **Find a file** - Press `T` (in Focus Mode) to open the file finder. Type `README` and press `Enter`. You just navigated straight to a file without scrolling. +5. **Read the README** - Press `1` to find the page title, then `2` to scan sections. + +**You're done.** You just toured a real repository using only your keyboard. + +> **What success feels like:** You visited four tabs and opened a file without touching a mouse. Every repository on GitHub has this same layout - you now know how to navigate all of them. + + +> ### Day 2 Amplifier - Accessibility Agents: `@daily-briefing` +> +> **Navigate every folder of [accessibility-agents](https://github.com/Community-Access/accessibility-agents) manually today before using any agent.** Find `.github/agents/`, open a `.agent.md` file, and read it - that file is how an agent knows what to do. You must understand the structure before you can evaluate whether an agent understood it correctly. +> +> Once you have mastered manual repository navigation: +> +> - **In VS Code** - `@daily-briefing morning briefing` sweeps every repository you have access to and delivers one prioritized document: open issues, PR status, CI results, security alerts, community reactions - all without opening a browser tab +> - **In your repo** - Fork [accessibility-agents](https://github.com/community-access/accessibility-agents) and the `.github/agents/` folder travels with every clone; every collaborator on your fork has access to the same agents you do +> - **In the cloud** - GitHub Agentic Workflows can generate daily status reports on a schedule, running inside GitHub Actions and posting digests to a designated issue thread - no VS Code, no local setup required +> +> *An agent's output only makes sense when you already know what it is describing. You are building that knowledge right now.* + + +> **Next Step:** Move on to [Chapter 04: The Learning Room](04-the-learning-room.md) to understand where we'll be practicing our new skills. + +--- + + +*Next: [Chapter 04: The Learning Room](04-the-learning-room.md)* +*Back: [Chapter 02: Understanding GitHub](02-understanding-github.md)* +*Related appendices: [Appendix B: Screen Reader Cheat Sheet](appendix-b-screen-reader-cheatsheet.md)* + diff --git a/admin/qa-bundle/docs/04-the-learning-room.md b/admin/qa-bundle/docs/04-the-learning-room.md new file mode 100644 index 0000000..143560a --- /dev/null +++ b/admin/qa-bundle/docs/04-the-learning-room.md @@ -0,0 +1,892 @@ +# The Learning Room: Your Personal Practice Repository +> +> **Listen to Episode 4:** [The Learning Room](../admin/PODCASTS.md) - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. + +> **Related appendices:** [Appendix A: Glossary](appendix-a-glossary.md) | [Appendix C: Markdown Reference](appendix-c-markdown-reference.md) +> **Authoritative sources:** [GitHub Docs: About README files](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes) | [GitHub Docs: Editing files](https://docs.github.com/en/repositories/working-with-files/managing-files/editing-files) + + +## What Is the Learning Room? + +The **Learning Room** is your **own private GitHub repository** for the workshop. When you accept the GitHub Classroom assignment in Block 0, GitHub copies the [`Community-Access/learning-room-template`](https://github.com/Community-Access/learning-room-template) repository into the workshop classroom organization as `/learning-room-`. That copy is yours to use for the workshop - you have write access, your own branches, your own pull requests, and your own automated feedback from Aria the PR validation bot. + +You do **not** work directly in `Community-Access/learning-room-template`. Think of the template as the clean master copy facilitators maintain. Your work happens in the private Learning Room repository created for you by GitHub Classroom. + +Throughout this chapter and the rest of Day 1, "your Learning Room repository" or "your Learning Room repo" refers to this private copy. Every student gets one, and every copy starts from the same template files. You will not see other students' work in your repo, and they will not see yours - but everyone is doing the same challenges in parallel. Peer-simulation issues and pull requests inside your repo provide realistic collaboration practice, and facilitators may also pair students for real peer review when access is intentionally provided. + +You do **not** need to create a GitHub organization or change repository permission settings. The workshop organization, template repository, Classroom assignment, and GitHub Actions permissions are managed by the facilitators. + + +## Why a Per-Student Repo? + +GitHub Classroom gives each participant their own repository for three reasons: + +- **Safety** -- you can experiment, break things, and recover without affecting anyone else +- **Authenticity** -- you practice real repository work: issues, branches, pull requests, checks, reviews, and merging +- **Pace** -- you progress through the 9 Day 1 challenges as fast or as slow as you need; nobody is waiting on you and you are not blocking anybody else + +Real open source projects are shared spaces, and you will absolutely contribute to one on Day 2 (`accessibility-agents`) and through the Bonus C challenge. The Learning Room exists so you can build the muscle memory for issue, branch, PR, review, merge in a space where every mistake is a learning opportunity, not a public problem. + + +## Step-by-Step: Accept Your Classroom Assignment and Open Your Repo + +This is the very first hands-on step of Day 1. By the end of this walkthrough you will have your own Learning Room repository on GitHub and your first challenge issue waiting for you. The whole flow takes about five minutes. + +> **What you need before you start:** +> +> - A GitHub account you are signed into in your browser ([Pre-Workshop Setup, Step 1](00-pre-workshop-setup.md#step-1---create-your-github-account)) +> - The **Day 1 Classroom assignment link** -- the facilitator pastes this link in the workshop chat at the start of Block 0. It looks like `https://classroom.github.com/a/`. If you do not have it, ask in chat or DM the facilitator. + +### 1. Open the assignment link + +1. In the same browser where you are signed into GitHub, open the Day 1 assignment link the facilitator shared. +2. The page that loads is hosted on `classroom.github.com`. Your screen reader announces a heading with the assignment name (for example, "Git Going with GitHub -- Day 1"). +3. If the page asks you to authorize **GitHub Classroom** to access your GitHub account, activate **Authorize GitHub Classroom**. This is a one-time step. + +### 2. Identify yourself (if asked) + +GitHub Classroom may ask you to pick your name from a roster so the facilitators can match your GitHub username to the registration list. + +1. If a roster page appears, navigate the list with arrow keys or use Find-in-Page (`Ctrl+F` / `Cmd+F`) to search for your name. +2. Activate the link or button next to your name. +3. If you do not see your name on the roster, activate the **Skip to the next step** link and tell the facilitator in chat. They will reconcile the roster after your repo is created. + +### 3. Accept the assignment + +1. You now see a screen with a button that says **Accept this assignment** (or just **Accept the assignment**). Activate it. +2. The page changes to a status screen that says something like "You are ready to go!" with a refresh option. GitHub Classroom is now copying the `learning-room-template` repository into the workshop classroom organization and granting you access to your private copy. This usually takes 10-30 seconds. +3. Activate the **Refresh** link (or reload the page with `F5`) every 15 seconds or so until you see a link to your new repository. The link looks like `https://github.com//learning-room-`. + +> **Screen reader tip:** The status page does not auto-announce when the repo is ready. Use Browse mode and press `K` to step through links until you hear your repository link, or refresh the page until it appears. + +### 4. Open your new repository + +1. Activate the link to your repository. You land on the standard GitHub repo page for `/learning-room-`. +2. Verify three things on this page: + - The **repo name** in the heading matches `learning-room-`. + - The **About** sidebar (or repo description) confirms this is a private workshop copy. + - You see folders like `docs/`, `.github/`, and files like `README.md`. These came from the template. +3. Bookmark this page. You will return here for every Day 1 challenge. + +### 5. Find your first challenge issue + +When your Learning Room repo is ready, **Challenge 1** appears as a GitHub issue in your repo. The facilitators prepare this by running the Student Progression Bot after students accept the Classroom assignment. The next challenges unlock one at a time as you close the previous ones. + +1. From your repository page, navigate to the **Issues** tab. Keyboard shortcut: press `G` then `I`. +2. You should see at least one open issue with a title like **"Challenge 1: Find Your Way Around"** authored by `aria-bot` (or `github-actions[bot]`). +3. Open Challenge 1. Read the issue body -- it tells you what to do, where to find evidence, and how to submit completion. + +> **If Challenge 1 is missing after 2 minutes:** Refresh the Issues tab once. If it still does not appear: +> +> 1. Open the **Actions** tab and check whether the **Student Progression Bot** workflow ran successfully. +> 2. If it failed or never ran, post a message in the workshop chat with the link to your repo. The facilitator can trigger `student-progression.yml` or create Challenge 1 from the issue template. + +### 6. Confirm Aria can talk to you + +The PR validation bot, **Aria**, posts educational feedback whenever you open a pull request. To confirm Aria is wired up, open the **Actions** tab in your repo and look for a workflow named **pr-validation-bot** (or **Aria PR Validation**). The workflow should appear in the list even before you have opened a PR. You do not need to run anything yet -- you just want to confirm it exists. + +You are now done with Block 0. Continue with the chapter below to learn how the Learning Room is organized, then jump to [Chapter 5](05-working-with-issues.md) to start Challenge 1. + + +## Workshop Recommendation (Chapter 4) + +Chapter 4 is a **system orientation chapter**. + +- **Challenge count:** none +- **Automation check:** none +- **Why:** this chapter explains how your repo is set up and prepares you for the issue-based challenges that start in Chapter 5. + +### Readiness Checkpoint + +Before starting Chapter 5 challenges, you should be able to: + +1. Find `docs/CHALLENGES.md` in your Learning Room repository. +2. Explain the flow: issue -> branch -> pull request -> review -> merge. +3. Identify where Aria bot feedback appears on a PR (the Conversation tab). + + +## Two Tracks That Reinforce Each Other + +Throughout Day 1 you work on **two parallel learning tracks**, both in your own account: + +### Track 1: GitHub Skills Modules (Optional Self-Paced Practice) + +- **[Introduction to GitHub](https://github.com/skills/introduction-to-github)** - Create branch, open PR, merge +- **[Communicate Using Markdown](https://github.com/skills/communicate-using-markdown)** - Write headings, links, code, tables +- **[Review Pull Requests](https://github.com/skills/review-pull-requests)** - Comment, approve, suggest changes + +**Scope:** Your personal account, optional and self-paced +**Bot:** Mona (GitHub's automated learning bot) guides each step +**Purpose:** Hands-on practice of individual skills, complementary to the workshop + +### Track 2: Your Learning Room Repository (Required Workshop Track) + +- **Blocks 1-4 (Day 1 morning/afternoon):** Challenges 1-7 -- find your way, file an issue, branch, commit, open a PR, survive a merge conflict +- **Block 5 (Day 1 evening):** Challenges 8-9 -- culture and merge day +- **Block 6 (Day 1 evening):** Community tools (labels, milestones, notifications) + +**Scope:** Your private Learning Room repository (created from `learning-room-template` via Classroom) +**Bot:** **Aria** -- a PR validation bot that posts educational feedback on every push, plus a Student Progression bot that auto-creates the next challenge issue when you close the current one +**Purpose:** End-to-end practice of the full workflow in a real repository where you have full control + +#### How the Two Tracks Compare + +| Step | GitHub Skills (optional) | Your Learning Room (required) | +| --- | --- | --- | +| 1 | Create a branch in a Skills repo | Create a branch in your Learning Room | +| 2 | Open a PR | Open a PR | +| 3 | Get instant bot feedback from Mona | Get instant bot feedback from Aria | +| 4 | Mona verifies your step | Aria validates structure; you self-merge or peer-review | +| 5 | Next Skills step unlocked | Closing the issue auto-unlocks the next challenge | + +### Learning Cards: Two Tracks, One Account + +
    +Screen reader users + +- GitHub Skills modules run in your personal account; press `G I` from any Skills repo to see the issue thread where Mona posts instructions +- Your Learning Room repository lives at a different URL inside the workshop organization; bookmark it and use `Alt+D` (address bar) to confirm which repo you are in +- Aria's bot comments on your PRs appear as PR conversation comments; press `3` on the PR page to jump between them + +
    + +
    +Low vision users + +- GitHub Skills repos have a distinct green banner at the top of the README that says "Start course"; your Learning Room repo has no such banner +- Check the repository name in the top-left header to confirm which track you are working in (Skills repo vs. your Learning Room) +- Aria's avatar appears next to bot comments; your human reviewer's avatar appears next to peer review comments + +
    + +
    +Sighted users + +- Skills modules appear as separate repos under your account page (github.com/your-username); your Learning Room appears under the workshop organization assigned by your facilitators +- Aria's comments have a distinct grey bot badge next to the username, just like Mona's +- Keep both repos open in separate browser tabs so you can switch between tracks during the workshop + +
    + + +## Your Learning Room Folder Structure + +Every Learning Room repository (yours and every other participant's) starts as an exact copy of `learning-room-template` and contains these files and folders: + +- **README.md** -- Getting started guide +- **.github/** + - **STUDENT_GUIDE.md** -- How the bot works + - **IMPLEMENTATION_GUIDE.md** -- Full setup walkthrough + - **SETUP_AND_MAINTENANCE.md** -- Maintenance reference + - **workflows/** -- 3 automation workflows + - learning-room-pr-bot.yml (PR validation) + - student-progression.yml (challenge delivery) + - skills-progression.yml (achievement tracking) + - student-grouping.yml (peer pairing) + - **scripts/** + - validate-pr.js (validation logic) + - **data/** + - student-roster.json (your cohort info) + - challenge-progression.json (levels, badges) +- **docs/** + - CHALLENGES.md -- 21 challenges (16 core + 5 bonus) + - welcome.md -- Has a TODO to complete + - keyboard-shortcuts.md -- Has intentional errors + - setup-guide.md -- Has broken links +- Other files for practice + + +## Your Practice Branch + +In your own Learning Room repository, **you decide what branches to create**. The Day 1 challenge sequence asks you to work on a single feature branch named after yourself: + +> **Branch naming convention for Day 1:** `learn/` (all lowercase) + +**Examples:** +- If your GitHub username is `payown`, your branch is `learn/payown` +- If your username is `BudgieMom`, your branch is `learn/budgiemom` +- If your username is `Weijun-Zhang-1996`, your branch is `learn/weijun-zhang-1996` + +### Why you create a separate branch + +- **Protected main branch** - The `main` branch in your Learning Room is protected; changes have to land via pull request even though you own the repo. This mirrors how mature open source projects work. +- **Your workspace** - Your `learn/` branch is where you commit and push changes before opening a PR +- **Clean history** - Keeping experiments off `main` until they are reviewed (by you, by Aria, or by a peer) keeps your project history easy to read +- **Realistic workflow** - Contributors to real open source projects always create feature branches before opening a PR. You are practicing exactly that pattern. + +### How to use your branch + +The Day 1 challenges (4 onward) walk you through creating and using your branch on GitHub.com. Once you start working locally in Chapter 14, the same branch is what you check out: + +```bash +git checkout learn/ +``` + +1. Create the branch on GitHub.com (Challenge 4) or locally with `git checkout -b learn/` from `main` +2. Make your changes and commit them to the branch +3. Push the branch to GitHub if you created it locally +4. Open a pull request from `learn/` -> `main` (Challenge 6) + +> **Which branch do I use and when?** +> +> | Chapter | Branch needed? | What to use | +> |---------|---------------|-------------| +> | Chapter 5 (Issues) | No | Work happens in issue threads directly. No branch or file editing required. | +> | Chapter 6 (PRs, web editor) | Yes | Create `learn/` from `main` (Challenge 4) and edit on it. | +> | Chapter 6 (PRs, local clone) | Yes, create manually | `git checkout -b learn/` from `main`. | +> | Chapter 14+ (Local Git) | Yes | Reuse `learn/`, or create additional `fix/` branches from `main` for new work. | +> +> **Summary:** Chapter 5 needs no branch. Chapters 6-7 use the same `learn/` branch. Day 2 reuses that branch and adds short-lived `fix/` branches when you tackle additional issues. + +### Learning Cards: Your Practice Branch + +
    +Screen reader users + +- To switch branches on GitHub.com, press `W` (in Focus Mode) to open the branch selector, type your branch name (`learn/`), and press `Enter` when it appears +- In VS Code's terminal, type `git checkout learn/` (lowercase) +- Press `Ctrl+Shift+G` in VS Code to open Source Control; the current branch name is announced at the top of the panel + +
    + +
    +Low vision users + +- The branch selector button shows the current branch name (e.g., "main") above the file table; click it and type "learn" to filter to your branch +- After switching branches, the branch name updates in the selector button; verify it reads `learn/`, not "main" +- In VS Code, the current branch name appears in the bottom-left corner of the Status Bar in small text; zoom in or check Source Control panel header for a larger display + +
    + +
    +Sighted users + +- The branch selector is the dropdown button above the file table showing the current branch name with a down-arrow icon +- Your branch follows the pattern `learn/` (all lowercase); type "learn" in the dropdown search to find it quickly +- In VS Code, the current branch is shown in the bottom-left of the Status Bar; click it to switch branches via a dropdown + +
    + + +### Tool Cards: Switch to Your Practice Branch + +**github.com (browser):** +1. On the repository page, click the branch selector dropdown (shows "main"). +2. Type `learn` to filter, then select `learn/`. + +**github.dev (web editor):** +1. Click the branch name in the bottom-left status bar. +2. Select your `learn/` branch from the list. + +**VS Code Desktop:** +1. Click the branch name in the bottom-left status bar (or press `Ctrl+Shift+P` then type **Git: Checkout to**). +2. Select `origin/learn/` from the branch list. + +**GitHub Desktop:** +1. Click the **Current Branch** dropdown at the top. +2. Type `learn` to filter, then select `learn/`. + +**Git CLI (terminal):** +```bash +git checkout learn/ +``` + +--- + +## The Practice Files: What You Will Work On + +> **See also:** [Appendix C: Markdown Reference](appendix-c-markdown-reference.md) covers all Markdown syntax with accessible examples -- you will need it for editing these files. + +The `docs/` folder contains three practice files with intentional issues. These are the files you will edit, fix, and submit pull requests for during the contribution sprint. Here is exactly what you will encounter in each file. + +### docs/welcome.md - Introduction to Open Source Contribution + +This file introduces newcomers to open source. It has **three [TODO] sections** where content is missing: + +#### [TODO] 1 - "Who Can Contribute?" section +> +> [TODO: Add a paragraph explaining that contributors come from all backgrounds, skill levels, and countries. Emphasize that using assistive technology is not a barrier to contribution - in fact, AT users bring a perspective that improves projects for everyone.] + +#### [TODO] 2 - "Finding Something to Work On" section +> +> [TODO: Add two or three sentences about how to read an issue to decide if it is right for you. What questions should you ask yourself? Is the description clear enough? Is anyone else already working on it?] + +#### [TODO] 3 - "After Your Contribution Is Merged" section +> +> [TODO: Add a sentence or two about what this means for someone's GitHub profile and open source portfolio.] + +It also has a broken internal link that needs to be found and fixed. **Challenges 1 and 3** from CHALLENGES.md map directly to this file. + +### docs/keyboard-shortcuts.md - Screen Reader Shortcut Reference + +This is a comprehensive reference with tables for NVDA, JAWS, and VoiceOver shortcuts. It contains **intentional errors** in some shortcut references that students need to find and fix. + +The file has three major sections: + +- **NVDA (Windows)** - Single-key navigation, mode switching, reading commands +- **JAWS (Windows)** - Virtual cursor navigation, mode switching, reading commands +- **VoiceOver (macOS)** - Rotor navigation, VO commands for GitHub + +Plus cross-platform shortcuts for GitHub pages and common workarounds. + +**Challenge 2** asks you to add a missing shortcut to the correct table. When you edit this file, you must preserve the Markdown table formatting. The bot validates that tables remain well-formed. + +### docs/setup-guide.md - Getting Ready to Contribute + +This step-by-step guide walks through GitHub account setup, accessibility settings, screen reader configuration, and repository forking. It contains **broken links** that point to incorrect URLs and **incomplete steps**. + +Look for: + +- Links to GitHub settings pages that may have changed +- A `[TODO]` note at the bottom referencing items for facilitators +- Steps that reference forking a "workshop repository" without providing the actual URL + +This file is used for **intermediate and advanced challenges** (Challenges 4-6) where students fix heading hierarchy, improve link text, and add missing descriptions. + +### docs/CHALLENGES.md - Your Challenge Menu + +This file lists all 21 challenges organized by progression level: + +| Level | Challenges | Requirement | +| ------- | ----------- | ------------- | +| Explorer (01-03) | Scavenger hunt, first issue, join conversation | Getting started | +| Contributor (04-07) | Branch out, make your mark, first PR, merge conflict | 3+ challenges | +| Collaborator (08-09) | Culture reflection, merge day | 7+ challenges | +| Operator (10-11) | Go local, Day 2 PR | 9+ challenges | +| Reviewer (12-14) | Code review, Copilot, issue template | 11+ challenges | +| Agent Navigator (15-16) | Agents, capstone | 14+ challenges | +| Bonus (A-E) | Accessibility audit, mentor, cross-repo, workflow, docs | Optional | + +Each challenge lists the file(s) to edit, estimated time, skills practiced, and success criteria. + +### Bonus Challenges + +Five bonus challenges (A through E) are available for students who finish faster. These include an accessibility audit, mentoring a peer, cross-repository contribution, creating a custom workflow, and documentation improvement. + + +## How PR Sharing Works + +### Step 1: Student Opens a PR + +#### Student A (working on Challenge 3: Complete Welcome Guide) + +1. Finds their assigned issue (Issues tab → filter `Assignee:@me`) +2. Opens `docs/welcome.md` and edits the three `[TODO]` sections +3. Commits to a new branch: `fix/studentA-issue12` +4. Opens a pull request with description: + + ```markdown + ## What Changed + Completed the three [TODO] sections in docs/welcome.md: + - Added contributor backgrounds paragraph + - Added guidance on evaluating issues + - Added note about GitHub profile impact + + Closes #12 + ``` + +5. **Submits the PR** + +**Visibility:** The PR immediately appears in the repo's Pull Requests tab. All students can see it. + +### Step 2: Automation Bot Validates + +#### Bot (`.github/workflows/learning-room-pr-bot.yml`) + +- Runs within 30 seconds +- Checks: + - Issue reference (does PR link to issue with `Closes #12`?) + - File location (only `docs/` directory files changed?) + - Markdown accessibility (headings, links, alt text, broken links) + - [TODO] markers (all three removed from welcome.md?) +- Posts a comprehensive comment with: + - Required checks (must pass) + - Suggestions (optional improvements) + - Accessibility analysis (detailed issues + fixes) + - Learning resources (links to docs) +- Applies labels (documentation, accessibility, needs-review) +- Creates commit status check visible in PR checks + +**Visibility:** The bot comment appears in your PR. You see it; the facilitators see it; nobody else does unless they have been added as a collaborator on your repo. + +### Step 3: Peer Review (Facilitator-Arranged) + +The `learning-room-template` ships with a peer-pairing workflow (`.github/workflows/student-grouping.yml`) that was designed for a single shared repo. Under the GitHub Classroom model used in this workshop, **peer review is arranged by the facilitators rather than auto-assigned**, because each student's repo is private. + +When Challenge 3 ("Join the Conversation") or Challenge 8 ("Culture") asks for peer review: + +1. The facilitators (Jeff and Michael) pair you with another participant. +2. They add each of you as a collaborator on the other's Learning Room repo. +3. Each of you receives a notification: "You have been added as a collaborator." +4. You can now read the other person's PRs, leave comments, request changes, and approve. +5. After the challenge is complete, the collaborator access remains until the workshop ends -- you can keep helping each other as you work through the rest of Day 1. + +#### Visibility + +- You see PRs in the repos you have been added to (yours plus any peers you have been paired with) +- Notifications show review requests in your GitHub Notifications inbox +- Other participants in the cohort cannot see your repo unless they are paired with you + +### Step 4: Reviewer Reads and Comments + +#### Your assigned peer reviewer (when one is paired with you) + +1. Receives notification: "PR review requested" +2. Navigates to the PR in your Learning Room repo (they have collaborator access) +3. Reads: + - PR title: "Complete [TODO] sections in welcome.md" + - PR description: lists which sections were completed + - Aria's feedback: checks that all `[TODO]` markers are removed, heading hierarchy is valid + - The actual file changes (Files Changed tab): sees the diff showing old `[TODO]` markers replaced with new content +4. Leaves review comments: + - Inline comment on the "Who Can Contribute?" paragraph: "Great addition - I especially like the point about AT users bringing valuable perspective." + - Overall comment: "The content reads well and all TODOs are resolved. One suggestion: the 'Finding Something to Work On' section could mention checking if an issue already has an assignee." +5. Submits review: **Approve** (or **Request Changes** if a `[TODO]` marker was missed) + +#### Visibility + +- You (the PR author) get a notification: "Your PR has a new review" +- The reviewer's comments appear in your PR thread +- Their name shows in the Reviewers sidebar of your PR + +### Step 5: Author Responds and Updates + +#### You (PR author) + +1. Read Aria's feedback and any human review +2. Talks to the reviewer if something is unclear +3. Makes changes based on feedback +4. Pushes new commits to the same branch +5. Re-addresses the feedback + +#### Visibility + +- Aria re-validates on each new commit and updates its comment +- Your reviewer sees the updated activity in the PR +- The PR timeline shows iteration happening + +### Step 6: Merge and Celebration + +#### When the review is approved (or you decide to self-merge) + +- You merge the PR (button becomes available) +- PR closes, shows "merged" + +#### Progression Bot Posts the Next Challenge + +- The Student Progression bot detects the merged PR and the closed challenge issue +- Posts a celebration comment (challenge badge earned) +- Auto-creates the next challenge issue in your repo so you can keep moving +- Updates the progress tracking file + +#### Visibility + +- You see the merged PR and the new challenge issue +- Your peer reviewer (if you have one) is notified the PR was merged +- Other participants only see this if they have been paired with you + +### Learning Cards: How PR Sharing Works + +
    +Screen reader users + +- When a bot comment appears on your PR, press `3` on the Conversation tab to jump between comment headers; bot comments include the bot's username in the heading +- To find your assigned reviewer, press `D` to reach the sidebar landmark, then `H` until you hear "Reviewers" -- your reviewer's username follows +- When you receive a "review requested" notification, press `G N` from any GitHub page to go to Notifications and find the review request + +
    + +
    +Low vision users + +- Bot comments are visually indented and often have a colored banner (green for pass, yellow for warnings); zoom in on the banner text for the summary +- The Reviewers section in the PR sidebar shows a small avatar and username; at high zoom avatars may overlap -- read the text username instead +- Merge button turns green when all required checks pass and the reviewer approves; it appears at the bottom of the Conversation tab + +
    + +
    +Sighted users + +- Bot comments appear in the PR timeline with a small "bot" badge next to the commenter's name +- The green "Merge pull request" button appears at the bottom of the Conversation tab once all checks pass and the reviewer approves +- The PR sidebar (right side) shows Reviewers, Assignees, Labels, and Linked Issues; each section has its own heading + +
    + + +## What You and Your Peers See + +| What | Where | Who Sees It | +| ------ | ------- | ----------- | +| Your open PRs | Pull Requests tab in your repo | You, the facilitators, and any peers added as collaborators | +| PR description & changes | PR page in your repo | Same as above | +| Aria's bot feedback | PR comments | Same as above | +| Peer review comments | PR comments | Same as above | +| Reviewer assignments | PR sidebar "Reviewers" | Same as above | +| Progression bot's next-challenge issue | Issues tab in your repo | Same as above | +| Your review requests for someone else's PR | Your notification inbox | You and the PR author you were paired with | + + +## The Learning Automation System + +When you open a PR in the Learning Room, you get **three types of feedback**: + +### Type 1: Automated Bot Feedback (30 seconds) + +- Technical validation (links, headings, file locations) +- Accessibility checking (detailed) +- Educational messaging (WHY each thing matters) +- Links to learning resources +- Never fails the PR; always educational + +### Type 2: Peer Reviewer Feedback (15-60 minutes) + +- Human judgment on content +- Creative suggestions +- Encouragement and mentorship +- Understanding of context +- Can approve, request changes, or comment + +### Type 3: Progress Tracking (on merge) + +- Skill badges (Markdown Master, Accessibility Advocate) +- Level progression (Beginner → Intermediate → Advanced → Expert) +- Milestone celebrations (1st, 5th, 10th PR) +- Motivational comments + +**Together:** Instant technical feedback + human mentorship + visible progress + + +## Study Groups (Optional) + +If your facilitators create study groups, you will be paired with 2-3 other participants and added as collaborators on each other's Learning Room repos: + +1. **Group Issue Thread** - Private communication space for your group +2. **Shared Review Responsibility** - You review each other's work +3. **Collaborative Challenges** - Optional group exercises +4. **Peer Support** - Tag each other with questions + +### Example + +```text +Study Group #2: @studentA, @studentC, @studentE + +This is your collaboration space! +- Review each other's PRs (beyond automated pairing) +- Share tips and resources +- Support each other through challenges +- Celebrate each other's achievements +``` + + +## Key Differences: Skills Module vs. Your Learning Room + +| Aspect | GitHub Skills (Your Account) | Your Learning Room (Classroom) | +| -------- | --- | --- | +| **Repo** | Your personal copy of a Skills repo | Your private copy of `learning-room-template` | +| **Bot** | Mona (GitHub) | Aria (PR validation) and the Student Progression bot | +| **Reviewer** | Mona (auto) | You (self-merge) or a peer paired by your facilitator | +| **Visibility** | Private to you (unless you make it public) | Private to you and the workshop organization | +| **Pace** | Self-directed | Self-paced, anchored by the workshop schedule | +| **Purpose** | Individual skill building | End-to-end practice of the full real-world workflow | +| **Feedback** | Instant, next-step only | Bot feedback on every push plus optional peer review | +| **Completion** | Badge on your profile | Closing the issue auto-creates the next challenge | +| **Community** | You alone | You, with facilitator-arranged peer pairings when challenges call for it | + + +## Tips for Reviewing a Peer's PR + +When the facilitators pair you with another participant for Challenge 3 or Challenge 8, you will be added as a collaborator on their Learning Room repo. Here is how to find the PRs they want you to look at. + +### Finding PRs to Review + +
    +Visual / mouse users + +1. Go to your peer's Learning Room repo (the URL the facilitators sent you, or open it from your GitHub Notifications inbox) +2. Click the **Pull Requests** tab +3. Click the **Filters** dropdown -> "Review requested" -> your username +4. Click any PR title to open it + +
    + +
    +Screen reader users (NVDA / JAWS) + +```text +1. Go to your peer's Learning Room repo +2. Press D -> "Repository navigation" +3. Press K -> navigate to "Pull Requests" tab +4. Filter: Press F, type "review-requested:@me" +5. Press H repeatedly to navigate PR titles +6. Press Enter to open a PR +``` + +
    + +
    +Screen reader users (VoiceOver - macOS) + +```text +1. Go to your peer's Learning Room repo +2. VO+U -> Landmarks -> "Repository navigation" +3. Quick Nav K -> navigate to "Pull Requests" tab -> VO+Space +4. Filter: Quick Nav F, type "review-requested:@me", press Return +5. Quick Nav H (or VO+Cmd+H) to navigate PR titles +6. VO+Space to open a PR +``` + +
    + +### Reading a PR You're Assigned To + +
    +Visual / mouse users + +- **Conversation tab:** Scroll through the discussion. Reviewers are listed in the right sidebar. +- **Files Changed tab:** Changed files are in a tree on the left. Click a filename to jump to its diff. Green = added lines, red = removed lines. +- Line comments appear as inline cards within the diff. + +
    + +
    +Screen reader users (NVDA / JAWS) + +```text +Conversation Tab (reading reviews): + 1. Press H → navigate headings + 2. Listen for "Reviewers" heading (h3) + 3. Your name appears as reviewer + 4. Read bot comment + 5. Read peer feedback + +Files Changed Tab (what actually changed): + 1. Press H to navigate files + 2. Press T to explore file tree + 3. Read the diff with your screen reader + 4. Navigate line comments with H → nested headings +``` + +
    + +
    +Screen reader users (VoiceOver - macOS) + +```text +Conversation Tab (reading reviews): + 1. Quick Nav H or VO+Cmd+H → navigate headings + 2. Listen for "Reviewers" heading + 3. Your name appears as reviewer + 4. VO+Down to read bot comment and peer feedback + +Files Changed Tab (what actually changed): + 1. Quick Nav H to navigate file headings + 2. VO+U → Landmarks → "File tree" to explore files + 3. VO+Shift+Down to interact with the diff table, then VO+Down for lines + 4. Navigate line comments with Quick Nav H → nested headings +``` + +
    + +### Leaving a Review + +
    +Visual / mouse users + +1. Scroll to the comment box on the Conversation tab +2. Type your review comment +3. Click **"Review Changes"** (top-right of the Files Changed tab, or at the bottom of the PR page) +4. Select your review type: Comment / Approve / Request changes +5. Click **"Submit review"** + +
    + +
    +Screen reader users (NVDA / JAWS) + +```text +1. On Conversation tab, scroll to comment box +2. Switch to Focus Mode (NVDA+Space / Insert+Z) +3. Type your review comment +4. Tab to "Review Changes" button +5. Select review type: + - "Comment" (just feedback) + - "Approve" (good to merge) + - "Request changes" (needs fixes) +6. Tab to "Submit review" +7. Press Enter +``` + +
    + +
    +Screen reader users (VoiceOver - macOS) + +```text +1. On Conversation tab, Quick Nav F or VO+U → Landmarks → "Add a comment" +2. VO+Shift+Down to interact with the comment text area +3. Type your review comment +4. VO+Shift+Up → Tab to "Review Changes" button → VO+Space +5. Select review type: + - "Comment" (just feedback) + - "Approve" (good to merge) + - "Request changes" (needs fixes) +6. Tab to "Submit review" → VO+Space +``` + +
    + +### Responding to Feedback + +
    +Visual / mouse users + +1. Open your PR (Pull Requests tab → click your PR) +2. Read all comments and bot feedback +3. Click in the comment box to reply +4. Push your fixes to the same branch +5. Comment: "Updates pushed, ready for review" + +
    + +
    +Screen reader users (NVDA / JAWS) + +```text +1. Open your PR (find in Pull Requests tab) +2. Read all comments and bot feedback +3. Scroll to comment box +4. Type your response +5. Mention reviewers with @ if clarifying +6. Push your fixes to the same branch +7. Comment: "Updates pushed, ready for review" +``` + +
    + +
    +Screen reader users (VoiceOver - macOS) + +```text +1. Open your PR (find in Pull Requests tab → Quick Nav H to navigate PR titles) +2. Quick Nav H and VO+Down to read all comments and bot feedback +3. VO+U → Landmarks → "Add a comment" to reach the comment box +4. VO+Shift+Down → type your response +5. Mention reviewers with @ if clarifying +6. Push your fixes to the same branch +7. Comment: "Updates pushed, ready for review" +``` + +
    + +### Learning Cards: Tips for PR Sharing + +
    +Screen reader users + +- To find PRs assigned to you for review, navigate to Pull Requests tab and type `review-requested:@me` in the filter field; press `Enter` to apply +- On the Files Changed tab, press `3` to jump between file headings in the diff; press `Tab` to navigate to inline comment buttons +- When leaving a review, press `Tab` from the comment box to reach the "Review Changes" button; the review type selector uses radio buttons navigable with `Arrow` keys + +
    + +
    +Low vision users + +- In the Files Changed tab, additions are highlighted in green and deletions in red; use a high-contrast theme if these colors are hard to distinguish +- Inline review comments appear as small text boxes embedded in the diff; at high zoom they may be narrow -- resize the browser window wider if text wraps awkwardly +- The "Submit review" button changes appearance based on your selected review type; "Approve" shows a green icon, "Request changes" shows a red icon + +
    + +
    +Sighted users + +- The review filter `review-requested:@me` in the Pull Requests tab filters to only PRs waiting for your review +- On the Files Changed tab, click the "+" icon that appears when you hover over a line number to leave an inline comment at that exact line +- The "Review Changes" button (top-right of Files Changed tab) opens a dropdown with three radio options: Comment, Approve, or Request Changes + +
    + + +## FAQ: Pull Requests in Your Learning Room + +### "Can I see other students' PRs?" + +Not inside their Learning Room repos -- those are private to each student. **You can see other participants' work in two ways:** + +- During Challenge 3 ("Join the Conversation") and Challenge 8 ("Culture"), the facilitators pair you with classmates and add you as a collaborator on each other's repos so you can review. +- During Day 2 (and the Bonus C challenge), everyone contributes to the public `accessibility-agents` repo, where every PR is visible to everyone. + +### "What if I don't agree with my assigned reviewer?" + +When the facilitators pair you for peer review, the pairing is a starting point, not a mandate. You can request additional reviewers manually. Click "Reviewers" -> select someone else, or ask the facilitators to pair you differently. + +### "Will my PR get lost when everyone is working at once?" + +No. Your repo is your own; you only see your own PRs. Aria's feedback is on your PR alone, and any peer reviewer is specifically assigned to you. + +### "Can I comment on someone else's PR?" + +When the facilitators pair you for review, yes -- you will be added as a collaborator and can comment, approve, and request changes on their PR. On the public `accessibility-agents` repo, anyone can comment on any open PR. + +### "What if my reviewer doesn't respond?" + +Mention them directly in a PR comment: "@name, any thoughts on the changes I pushed?" Or ask a facilitator to follow up. + +### "Can I work with a friend?" + +The facilitators arrange peer pairings, but if you know someone else in the cohort and you want to review each other's work, ask either Jeff or Michael to add you to each other's repos. + +### "How long does review take?" + +When pairings happen during a workshop block, typically 15-60 minutes. If a reviewer is slow, the facilitators can step in or assign someone else. + +### "What if bot feedback is wrong?" + +Comment on the PR explaining why. Aria is intentionally educational, not punitive -- if you disagree with a check, the facilitators can override it. Aria is not perfect, which is exactly why human review still matters. + +### "Do I need to complete every challenge?" + +No. The Learning Room has challenges for all skill levels. You can pick what interests you, complete at your pace, and continue after the workshop -- your repo stays yours. + + +## If You Get Stuck + +| Problem | What to do | +|---|---| +| Cannot find your `learn/` branch | If you have not created it yet, follow Challenge 4. If you created it but cannot see it, refresh the branch selector or run `git fetch origin` from a local clone. | +| Push rejected to main branch | Main is protected. You need to push to your `learn/` branch: `git checkout learn/` then push again. | +| I want to see another student's PR | Ask a facilitator -- when peer review is part of a challenge, they will add you as a collaborator on the other student's repo. | +| Practice file has no TODO markers | Verify you are on the correct branch. Run `git branch` to see your current branch. The main branch may have already been updated. | +| Accidentally committed to main | Do not panic. See the failsafe instructions in [Chapter 13](13-how-git-works.md#10-if-you-get-stuck) or ask a facilitator. | +| Everything else | Post a comment on your challenge issue describing what happened. That always counts as participation. | +| I finished Challenge 4 but I am not sure I did it right | Compare your work against the [Challenge 4 reference solution](solutions/solution-04-branch-out.md). Any branch with any name is a success. | +| I finished Challenge 5 but I am not sure I did it right | Compare your work against the [Challenge 5 reference solution](solutions/solution-05-make-your-mark.md). Any clear edit with a descriptive commit message is a success. | + + +## Celebration: You're Contributing + +Every PR you open and merge in the Learning Room is a **real contribution**: + +You found something to improve +You made a meaningful change +You received feedback (technical + human) +You incorporated suggestions +You merged your work + +**That is open source contribution.** Your facilitator has a record. The GitHub repo has a record. You have a merged commit in your history. + +This is not hypothetical. This is not simulation. This is real. + + +> **Challenge Time:** Let's practice. Go to the [Challenge Hub](CHALLENGES.md) and complete **Challenge 1: Find Your Way Around**, then return for [Chapter 05: Working with Issues](05-working-with-issues.md). + +--- + + +*Next: [Chapter 05: Working with Issues](05-working-with-issues.md)* +*Back: [Chapter 03: Navigating Repositories](03-navigating-repositories.md)* +*Related appendices: [Appendix A: Glossary](appendix-a-glossary.md)* + diff --git a/admin/qa-bundle/docs/05-working-with-issues.md b/admin/qa-bundle/docs/05-working-with-issues.md new file mode 100644 index 0000000..c3b6b31 --- /dev/null +++ b/admin/qa-bundle/docs/05-working-with-issues.md @@ -0,0 +1,1468 @@ +# Working with Issues +> +> **Listen to Episode 5:** [Working with Issues](../admin/PODCASTS.md) - 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-n-advanced-search.md) | [Appendix V: GitHub Mobile](appendix-v-github-mobile.md) | [Appendix B: Screen Reader Cheat Sheet](appendix-b-screen-reader-cheatsheet.md) +> **Authoritative sources:** [GitHub Docs: About issues](https://docs.github.com/en/issues/tracking-your-work-with-issues/about-issues) | [GitHub Accessibility Guide: Issues](https://accessibility.github.com/documentation/guide/issues/) + + +## 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](https://accessibility.github.com/documentation/guide/issues/). 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](00-pre-workshop-setup.md#step-4---check-github-feature-preview-settings). +> +> **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 + +### Chapter 5 Challenge Set + +1. **Create your first issue** - file a new issue with a clear title and description. +2. **Comment and @mention** - leave a comment on a classmate's issue and tag them with an @mention. +3. **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. + +1. Open your Learning Room repository in your browser. +2. Navigate to the **Issues** tab (press `G` then `I` to jump there with keyboard shortcuts, or find the "Issues" link in the repository navigation). +3. Activate the **New issue** button. +4. If a template picker appears, select **Open a blank issue** (or choose a template if one fits). +5. 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 table has incorrect NVDA modifier key" + - "Setup guide link to accessibility settings is broken" +6. In the **Body** field, write a meaningful description (at least 80 characters). Include: + - What the problem is or what content is missing. + - Where in the repository the problem exists (file name and section). + - What you think the fix should be. +7. Activate **Submit new issue**. +8. Copy the issue URL or note the issue number (for example, `#150`). You will reference this later. + +**You are done when:** Your new issue appears in the Issues list with your username as the author, a clear title, and a detailed description. + +### Challenge 4.2 Step-by-Step: Comment and @Mention + +**Goal:** Leave a comment on another student's issue and use an @mention to notify them. + +**Where you are working:** the Issues tab of your Learning Room repository on GitHub.com. + +1. Open the **Issues** tab in your Learning Room repository. +2. Find an issue created by a classmate (look for issues from Challenge 4.1, or browse recent open issues). +3. Open the issue by activating its title link. +4. Read the issue description to understand what they reported. +5. Scroll to the comment box at the bottom of the issue. +6. Write a helpful comment that **@mentions the issue author by username**. Examples: + - "@classmate I can confirm this - the link in setup-guide.md goes to a 404 page." + - "@classmate Good catch! I think the correct shortcut is Insert+F7, not Insert+F5." + - "@classmate I'd suggest adding the paragraph right after the 'Who Can Contribute' heading." +7. Activate the **Comment** button (or press `Ctrl+Enter`). + +**Why @mentions matter:** When you type `@username`, GitHub sends that person a notification. This is how real open source teams communicate - you signal who needs to see your message. It also bridges into Chapter 10 (Notifications) where you will configure how you receive these alerts. + +**You are done when:** Your comment appears in the thread and includes an @mention (the username renders as a clickable link). + +### Challenge 4.3 Step-by-Step: Add a Sub-Issue + +**Goal:** Break a larger issue into smaller, trackable pieces using GitHub's sub-issue feature. + +**Where you are working:** the issue you created in Challenge 4.1 (or any open issue you have permission to edit). + +> **What are sub-issues?** Sub-issues let you decompose a big task into smaller steps, each tracked independently. The parent issue shows a progress bar as sub-issues are completed. This is how teams organize real work - a single "Fix accessibility in welcome.md" issue might have sub-issues for each specific fix. + +1. Open the issue you created in Challenge 4.1. +2. Look for the **Sub-issues** section in the issue sidebar (right side on desktop). If you do not see it, look for an **Add sub-issue** button or the **Create sub-issue** option below the issue description. +3. Activate **Add sub-issue** and choose **Create new sub-issue**. +4. Give the sub-issue a clear title that describes one specific piece of the parent issue. For example, if the parent is "Fix accessibility in welcome.md": + - Sub-issue: "Add alt text to welcome banner image" + - Sub-issue: "Fix heading hierarchy in Getting Started section" +5. Add a short description and activate **Create**. +6. The sub-issue now appears nested under the parent issue with a progress indicator. + +**You are done when:** Your parent issue shows at least one sub-issue in the Sub-issues section. + +### Completing Chapter 4: Submit Your Evidence + +When you have finished all three challenges, go to your **assigned Chapter 4 challenge issue** (the one titled "Chapter 4.1: Create Your First Issue (@yourusername)" or similar) and post a comment with your evidence: + +```text +Chapter 4 completed: +- Challenge 4.1: Created issue #[number] +- Challenge 4.2: Commented with @mention on issue #[number] +- Challenge 4.3: Added sub-issue to issue #[number] +``` + +Replace `[number]` with the actual issue numbers. Then close your Chapter 4 challenge issues. The facilitator will review your issue activity. + +### Expected Outcomes + +- Student can create an issue with a clear title and description. +- Student can communicate in issue threads using @mentions. +- Student can organize work by breaking issues into sub-issues. + +### If You Get Stuck + +1. Can't find a classmate's issue? Filter the Issues tab by `is:open` and look for recent ones. +2. @mention not working? Make sure you type `@` immediately followed by the username with no space. +3. Sub-issue option not visible? Ask a facilitator - the feature may need to be enabled for the repository. +4. Still stuck? Ask a facilitator for a direct issue link. +5. Finished but not sure you did it right? Compare your work against the [Challenge 2 reference solution](solutions/solution-02-first-issue.md) or the [Challenge 3 reference solution](solutions/solution-03-conversation.md). + +### Learning Moment + +Issues are collaborative spaces, not just task lists. An @mention tells someone "I need your attention here." Sub-issues turn vague tasks into clear checklists. Both skills are used daily in real open source projects. + +### Learning Pattern Used in This Chapter + +1. Start with a small, safe action (create an issue). +2. Practice communication in public issue threads (@mention a peer). +3. Organize work into smaller pieces (sub-issues). +4. Leave clear evidence in the issue timeline. +5. Build momentum for file editing and PR work in Chapter 6. + + +### About Learning Cards in This Chapter + +This chapter provides learning cards: expandable blocks that offer perspective-specific guidance for different ways of working. Not every card appears at every step. Open the ones that match how you work. + +The following table describes the five learning card types used in this chapter. + +| Card | Who it helps | What it covers | +| --- | --- | --- | +| Visual / mouse | Sighted users navigating with a mouse or trackpad | Click targets, visual cues, layout orientation | +| Low vision | Users with magnification, zoom, or high-contrast themes | Zoom-friendly navigation, finding controls at high magnification, high contrast visibility | +| NVDA / JAWS (Windows) | Screen reader users on Windows | Keystroke sequences, Focus and Browse mode, landmark navigation | +| VoiceOver (macOS) | Screen reader users on macOS | VO key sequences, rotor usage, interaction model | +| CLI (gh) | Terminal users on any platform | GitHub CLI commands for issue management | + + +## Local Git Alternative: Working from Your Clone + +
    +If you cloned the learning-room in Block 0 and prefer working locally + +During Block 0 you cloned the Learning Room repository to your computer. If you are comfortable in a terminal, you can use the GitHub CLI (`gh`) from inside that clone for every issue operation in this chapter. This is the same workflow covered in depth in [Chapter 11: Git and Source Control](14-git-in-practice.md). + +**Verify your clone is ready:** + +```bash +cd ~/Documents/learning-room # or wherever you cloned it +git status # should show "On branch main" +``` + +**Common issue commands from your local terminal:** + +```bash +# List your assigned challenge issues +gh issue list --assignee @me --label challenge + +# View a specific issue in the terminal +gh issue view 42 + +# Leave a comment on an issue +gh issue comment 42 --body "I'd like to try this!" + +# Create a new issue interactively +gh issue create +``` + +All of these produce the same result as the web interface. The chapter instructions work identically either way - choose whichever is more comfortable for you. + +
    + + +## What Is a GitHub Issue? + +An issue is a discussion thread attached to a repository. Issues are used for: + +- **Bug reports** - "This feature doesn't work when using a screen reader" +- **Feature requests** - "It would help if the submit button had an accessible label" +- **Questions** - "How do I configure X for Y use case?" +- **Tasks** - "Update the README with screen reader instructions" +- **Accessibility reports** - "The infinite scroll carousel is not keyboard accessible" + +Every issue has a **number** (`#42`), a **state** (Open or Closed), a **title**, a **description**, and a **comment thread**. Issues are public by default on public repositories. + +> **Learning Room connection:** In your Learning Room repo, every challenge from `docs/CHALLENGES.md` becomes an issue. For example, Challenge 1 ("Fix Broken Link") is filed as an issue pointing to `docs/welcome.md`, describing the broken link and linking to the challenge success criteria. When you open a PR to fix it, you reference the issue with `Closes #XX` to automatically close it on merge. + + +## Navigating to the Issues List + +### From a repository page + +
    +Visual / mouse users + +Click the **Issues** tab in the repository navigation bar below the repository name. The tab shows the open issue count (e.g., “Issues · 14”). + +
    + +
    +Screen reader users (NVDA / JAWS - Windows) + +1. Press `D` to navigate to the "Repository navigation" landmark +2. Press `K` or `Tab` to move through the tab links +3. Find "Issues" - it will be announced with the count: "Issues, 14 open" +4. Press `Enter` to open the Issues tab + +
    + +
    +Screen reader users (VoiceOver - macOS) + +1. `VO+U` → Landmarks → navigate to "Repository navigation" +2. `VO+Right` or Quick Nav `K` to move through tab links +3. Find "Issues" - VoiceOver announces the count: "Issues 14" +4. `VO+Space` to activate the Issues tab + +
    + +
    +GitHub CLI (gh) alternative + +List open issues directly from your terminal: + +```bash +gh issue list +``` + +Filter by label, assignee, or state: + +```bash +gh issue list --label "good first issue" +gh issue list --assignee @me +gh issue list --state closed +``` + +**Setup:** Install the GitHub CLI from [cli.github.com](https://cli.github.com) and authenticate with `gh auth login`. See [Appendix D](appendix-d-git-authentication.md) for details. + +
    + +### Direct URL + +Navigate directly: `https://github.com/[owner]/[repo]/issues` + +### Learning Cards: Navigating to the Issues List + +**Screen reader users:** +- Press `D` to jump to the "Repository navigation" landmark, then `K` or `Tab` to find the Issues link -- this is faster than arrowing through the entire page +- The Issues tab announces its open count ("Issues, 14 open"), giving you an instant sense of project activity without loading the list +- Use `gh issue list` in the terminal to bypass browser navigation entirely; pipe through `--label` or `--assignee @me` to pre-filter results + +**Low-vision users:** +- The Issues tab count badge may be small at default zoom; at 200%+ the tab text reflows but the count remains visible next to the word "Issues" +- Bookmark the direct URL pattern (`github.com/owner/repo/issues`) to skip repository page navigation altogether +- In high-contrast mode, the active tab is indicated with an underline using system highlight color, not just a subtle background change + +**Sighted users:** +- The Issues tab sits in the repository navigation bar directly below the repo name; the open count badge gives a quick pulse check on project health +- Memorize the `G I` keyboard shortcut (press G, release, press I) to jump to Issues from anywhere in the repository without scrolling +- The direct URL pattern works for any repository: swap `[owner]/[repo]` with real values and bookmark your most visited projects + + +## The Issues List Page + +### Page structure + +``` +[Search / filter bar] -- controls at the top +[State tabs: Open / Closed] -- filter by status +[Issues list] -- each issue is one list item or heading +[Pagination] -- at the bottom +``` + +> **Quick orientation tip:** Press `NVDA+F7` (or `VO+U` on macOS) to open a list of all headings, links, form fields, and buttons on the page. This is often faster than tabbing through many elements and helps you understand the full page structure before diving in. Use `Ctrl+/` (Windows) or `Cmd+/` (Mac) to jump directly to the search field from anywhere on the page. + +### How to read the issue list + +
    +Visual / mouse users + +The issues list shows each issue as a row with its title, labels, number, assignee avatars, and comment count. Closed issues show a purple merged/closed badge. Click any issue title to open it. Use the **Open** and **Closed** toggle links above the list to switch between states. + +
    + +
    +Low vision users (zoom, high contrast) + +Each issue row shows the title, labels (colored badges), number, and comment count. At high magnification: + +- Issue titles are the largest text in each row and remain readable at 200%+ zoom. +- Label badges use colored backgrounds with text inside. In Windows High Contrast mode, labels display with system border colors and readable text rather than colored backgrounds. +- The **Open** and **Closed** toggle links above the list let you switch views. The active toggle is bold or underlined. +- The comment count icon (a speech bubble) may be small at high zoom. It appears to the right of each issue row. Hover to see "N comments" tooltip. +- Use `Ctrl+F` (browser Find) to search for a specific issue title if the list is long. + +
    + +
    +Screen reader users (NVDA / JAWS) + +1. Press `D` to reach the “Search Results List” landmark +2. Press `3` (h3) to navigate by issue titles - each issue title is an h3 link +3. Press `I` to move between list items if you want more detail per item +4. Press `Enter` on a title to open that issue + +
    + +
    +Screen reader users (VoiceOver) + +1. `VO+U` → Landmarks → navigate to “Search Results List” +2. `VO+Down` to read through items +3. `H` (with Quick Nav on) or `VO+U` → Headings to jump by issue title + +
    + +### What is announced per issue + +When you navigate to an issue in the list, your screen reader will announce (in some order): + +- Issue title (as a link) +- Issue number (`#42`) +- Labels (e.g., "bug, good first issue") +- Who opened it and when ("Opened 3 days ago by username") +- Number of comments ("5 comments") + +### Learning Cards: The Issues List Page + +
    +Screen reader users + +- Press `D` to jump to the "Search Results List" landmark, then press `3` to navigate issue titles (each is an H3 link) +- Press `I` to move between individual list items if you want full detail per issue (number, labels, author, age) +- After applying a filter, the issue list updates silently; press `3` again to re-navigate the updated list from the top + +
    + +
    +Low vision users + +- Issue titles are the largest text per row and stay readable at 200%+ zoom; labels appear as small colored badges to the right of each title +- The Open/Closed toggle links are near the top of the list; the active state is bold or underlined depending on your theme +- If the comment count icon (speech bubble) is too small at your zoom level, hover over it for a tooltip showing the exact count + +
    + +
    +Sighted users + +- Each issue row shows: open/closed icon (green circle = open, purple merged icon = closed), title, label badges, PR link icon, comment count, and assignee avatar +- Click the Open/Closed tabs above the list to switch between open and closed issues; the count next to each tab updates as you filter +- Issue labels appear as colored rounded rectangles inline with the title; hover over a label to see its description + +
    + + +## Filtering and Searching Issues + +Filtering lets you narrow the list to find the right issue quickly. + +### Using the search/filter bar + +1. Press `F` or `E` to jump to the filter input field (or navigate from the landmark) +2. Switch to Focus Mode (`NVDA+Space` / `Insert+Z`) if not already in it +3. Type your filter or search query +4. Press `Enter` to apply + +#### Useful filter queries + +```text +is:open label:"good first issue" ← great for finding your first contribution +is:open label:accessibility ← accessibility-related open issues +is:open assignee:@me ← issues assigned to you +is:open no:assignee ← unassigned issues +is:open author:@me ← issues you filed +mentions:@me ← where you were @mentioned +is:open is:unread ← issues with unread activity +``` + +### Using the filter buttons + +Above the issue list, there is an **actions toolbar** with filter buttons for Labels, Milestones, Assignees, etc. + +> **Screen reader note:** The filter buttons do not indicate the current filter state. After applying a filter, the button text does not change to reflect what is selected. To verify which filters are active, check the search/filter bar text - it updates to show the active filter conditions (for example, `is:open label:accessibility`). + +
    +Visual / mouse users + +The filter bar sits above the issue list. Click **Label**, **Milestone**, or **Assignee** to open a dropdown, select the values you want, then click anywhere outside to close. The issue list updates immediately. + +
    + +
    +Low vision users (zoom, high contrast) + +The filter bar sits above the issue list. At high magnification: + +- The **Label**, **Milestone**, and **Assignee** buttons may wrap to a second row. Each button opens a dropdown with searchable options. +- Dropdown menus from filter buttons can extend below the visible viewport at high zoom. Scroll within the dropdown to see all options. +- Type in the search field at the top of each dropdown to narrow the list (for example, type "accessibility" in the Label dropdown). +- In Windows High Contrast mode, the selected filter values are indicated with a checkmark icon and system highlight color, not just a background color change. + +
    + +
    +Screen reader users (NVDA / JAWS - Windows) + +1. Press `Tab` from the search bar (or `Shift+Tab` from the issue list) to reach the actions toolbar +2. Press `←/→` to move between toolbar options (Label, Milestone, Assignee, Sort) +3. Press `Enter` to open the selected dropdown +4. Use `↑/↓` to navigate options in the dropdown +5. Press `Enter` or `Space` to select +6. Press `Escape` to close (filter applies immediately) + +
    + +
    +Screen reader users (VoiceOver - macOS) + +1. `Tab` forward from the search bar to reach the filter buttons, or use Quick Nav to find them +2. `VO+Left/Right` to move between Label, Milestone, Assignee, Sort buttons +3. `VO+Space` to open the selected dropdown +4. `VO+Down` or arrow keys to navigate the dropdown options +5. `VO+Space` to select/deselect +6. `Escape` to close (filter applies immediately) + +
    + +
    +GitHub CLI (gh) alternative - filtering + +Filter issues by label, milestone, or assignee without navigating dropdown menus: + +```bash +# Filter by label +gh issue list --label "accessibility" + +# Combine filters +gh issue list --label "good first issue" --assignee @me + +# Filter by milestone +gh issue list --milestone "Hackathon Day 1" + +# Search with keywords +gh issue list --search "screen reader" +``` + +
    + +### Open vs Closed filter + +The two state links "Open" and "Closed" appear near the top of the issue list. Press `K` to navigate links until you find them, or look for them as buttons near the search bar. + +### Learning Cards: Filtering and Searching Issues + +**Screen reader users:** +- Switch to Focus Mode (`NVDA+Space`) before typing in the filter bar; switch back to Browse Mode after pressing Enter to read the filtered results +- The filter bar does not announce how many results remain after filtering; press `H` to jump to the issue list heading, then listen for the count in the heading text +- Combine `gh issue list` flags (e.g., `--label "accessibility" --assignee @me`) for instant filtered results without navigating dropdown menus + +**Low-vision users:** +- Filter dropdown menus can extend below the viewport at high zoom; scroll within the dropdown or type in the search field at the top of each dropdown to narrow options +- After applying a filter, verify it took effect by checking the search bar text -- it updates to show active conditions like `is:open label:accessibility` +- The `Ctrl+/` (Windows) or `Cmd+/` (Mac) shortcut focuses the search bar instantly, avoiding the need to scroll up to find it + +**Sighted users:** +- Build compound queries in the search bar for precision: `is:open label:"good first issue" no:assignee` finds unclaimed starter issues in one step +- The Open/Closed toggle near the top of the list preserves your current filter; click Closed to see resolved issues without losing your label or assignee filter +- Pin your most-used filter as a browser bookmark (the URL updates to reflect the active query) for one-click access + + +## Reading an Issue + +### Landing on an issue page + +When you open an issue, the page structure is: + +```text +[Issue title - h1] +[Open/Closed status badge] +[Author, timestamp, comment count] +───────────────────────────────── +[Issue description - Main content] ← the original post +[Labels, Assignees sidebar - h3s] +───────────────────────────────── +[Activity / Timeline] ← comments and events + [First comment - h3] + [Second comment - h3] + ... +───────────────────────────────── +[Add a comment - landmark] +[Comment text area] +[Close issue / Submit button] +``` + +### Quick navigation + +| Goal | Key | +| ------ | ----- | +| Hear the issue title | `1` | +| Jump to description | `2` (first h2 is usually "Description") | +| Jump to Activity section | `2` → next h2 is "Activity" | +| Navigate between comments | `3` (each comment is h3) | +| Jump to comment box | `D` → "Add a comment" landmark | +| Navigate labels/assignees | `H` or `3` in the sidebar | + +### Reading the issue description + +1. Press `2` to reach the "Description" heading +2. Press `↓` to read the content line by line, OR +3. Use `NVDA+↓` (NVDA say all) to have it read continuously + +> **Browse Mode recommended:** The issue detail page is primarily text-based. Stay in **Browse Mode** (not Focus Mode) for reading - it gives you full heading (`H`), section (`D`), and link (`K`) navigation throughout the page. Only switch to Focus Mode when you need to type in a comment box. + +Markdown in the description renders as proper HTML: headings become actual headings, bullets become lists, code blocks become `` elements with the text "code block" announced. + +
    +GitHub CLI (gh) alternative - reading an issue + +View an issue's full content in your terminal: + +```bash +# View issue in terminal (renders Markdown) +gh issue view 42 + +# Open the issue in your browser instead +gh issue view 42 --web + +# View just the comments +gh issue view 42 --comments +``` + +The terminal output includes the title, state, labels, assignees, body, and comments. Markdown renders as plain text - headings use `#` symbols, lists use `-`, and code blocks are preserved. + +
    + +### Reading comments and activity + +Each comment in the thread is marked as an h3. Navigate between them with `3`. + +Each comment announces: + +- Commenter's username +- Timestamp ("2 days ago") +- Body text +- Reactions (if any - announced as a button with an emoji and count) +- A "Reply" link + +Other timeline events (label added, PR linked, issue closed) appear between comments in the activity stream. They are typically announced as text paragraphs. + +### Learning Cards: Reading an Issue + +
    +Screen reader users + +- Press `1` to hear the issue title, then `2` to reach "Description" and "Activity" headings, and `3` to jump between individual comments +- Stay in Browse Mode for reading; only switch to Focus Mode (`NVDA+Space`) when you need to type in the comment box +- Press `D` to jump to the "Add a comment" landmark at the bottom of the page to skip directly to the reply area + +
    + +
    +Low vision users + +- The issue title is the largest text on the page, followed by an Open/Closed badge in green or purple +- Comment blocks have a subtle border and a grey header bar showing the author's avatar and timestamp; zoom in on the header to identify commenters +- The sidebar (Labels, Assignees, Milestone) is on the right at desktop width; at high zoom it may move below the main content + +
    + +
    +Sighted users + +- The issue page has a two-column layout: main content on the left (description, timeline, comment box) and sidebar on the right (labels, assignees, milestone, linked PRs) +- Each comment shows the author's avatar in the left margin, with a header bar containing their username and a relative timestamp +- Timeline events (label changes, assignments, cross-references) appear as small lines between comments with icons indicating the event type + +
    + + +## Leaving a Comment + +### Step-by-step + +
    +Visual / mouse users + +1. Scroll to the bottom of the issue page +2. Click in the **Leave a comment** text area +3. Type your comment (Markdown is supported - use the toolbar buttons above the text for bold, italic, code, etc.) +4. Optionally click **Preview** to see how it will render +5. Click the green **Comment** button to post + +To close the issue while commenting: click the arrow on the **Close issue** button and choose **Close with comment**. + +
    + +
    +Low vision users (zoom, high contrast) + +The comment area is at the bottom of the issue page. At high magnification: + +1. Scroll to the bottom to find the **Leave a comment** text area. At 200%+ zoom, this may require significant scrolling past the timeline. +2. The text area expands as you type. The formatting toolbar above it (bold, italic, code, etc.) wraps at high zoom but remains functional. +3. The **Preview** tab next to **Write** lets you check Markdown rendering before posting. +4. The green **Comment** button is full-width at high zoom and easy to target. +5. **Keyboard shortcut:** Press `Ctrl+Enter` (Windows) or `Cmd+Return` (macOS) from inside the text area to submit the comment without finding the button. +6. In Windows High Contrast mode, the text area border and the Comment button use system colors for clear visibility. + +
    + +
    +Screen reader users (NVDA / JAWS - Windows) + +1. Navigate to the comment box: `D` → "Add a comment" landmark, or press `E` or `F` to focus the text area +2. Enter Focus Mode: NVDA: `Insert+Space` | JAWS: `Insert+Z` +3. Type your comment (plain text or Markdown) +4. To preview: `Tab` to the **Preview** button, press `Enter`; then `Tab` back to **Write** to continue editing +5. Submit: press `Ctrl+Enter` from inside the text area, OR press `Escape` → `Tab` to the **Comment** button → `Enter` + +
    + +
    +Screen reader users (VoiceOver - macOS) + +1. Navigate to the comment box: `VO+U` → Landmarks → "Add a comment", or Quick Nav `F` to jump to the text area +2. Interact with the text area: `VO+Shift+Down` +3. Type your comment (plain text or Markdown) +4. To preview: `VO+Shift+Up` to stop interacting, then `Tab` to the **Preview** button and `VO+Space` +5. Submit: press `Cmd+Return` from inside the text area, OR `VO+Shift+Up` → `Tab` to the **Comment** button → `VO+Space` + +
    + +
    +GitHub CLI (gh) alternative - commenting + +Leave a comment from your terminal: + +```bash +# Interactive: opens your default editor ($EDITOR) to write the comment +gh issue comment 42 + +# Inline: provide the comment text directly +gh issue comment 42 --body "Thanks for reporting this. I can reproduce the issue with NVDA + Chrome." +``` + +
    + +### Markdown formatting while typing + +These keyboard shortcuts work inside the text area (Focus Mode): + +| Shortcut | Result | +| ---------- | -------- | +| `Ctrl+B` | **Bold text** | +| `Ctrl+I` | *Italic text* | +| `Ctrl+E` | `Code span` | +| `Ctrl+K` | [Link text](URL) dialog | +| `Ctrl+Shift+.` | > Blockquote | +| `Ctrl+Shift+L` | - Bullet list | +| `Ctrl+Shift+7` | 1. Numbered list | + +### GitHub shortcuts for the Issues pages + +These are the GitHub built-in shortcuts for working with issues. Enable Focus Mode first (NVDA: `NVDA+Space`, JAWS: `Insert+Z`) before using single-key shortcuts. + +#### On the Issues list page + +| Shortcut | Action | +| --- | --- | +| `?` | Show all shortcuts for this page | +| `G I` | Jump to the Issues tab from anywhere in the repo | +| `C` | Create a new issue | + +**Shortcut note:** For `G I`, press `G`, release it, then press `I` (two sequential key presses, not simultaneous). +| `Ctrl+/` (Win) or `Cmd+/` (Mac) | Focus the issues search and filter bar | +| `U` | Filter by author | +| `L` | Filter by or edit labels | +| `M` | Filter by or edit milestones | +| `A` | Filter by or edit assignee | +| `O` or `Enter` | Open the selected issue | + +#### On an open issue + +| Shortcut | Action | +| --- | --- | +| `M` | Set a milestone | +| `L` | Apply a label | +| `A` | Set an assignee | +| `X` | Link a related issue from the same repository | +| `R` | Quote selected text in your reply (select text first) | +| `Ctrl+Shift+P` (Win) or `Cmd+Shift+P` (Mac) | Toggle Write and Preview tabs | +| `Ctrl+Enter` | Submit comment from inside the text area | + +> **`R` to quote is a power move:** Select any text in a comment while in Browse Mode (`Shift+Arrow` to select), then press `R`. GitHub puts the quoted text in the comment box as a Markdown blockquote. Much faster than typing `>` manually. + +For the full shortcut system, see [Screen Reader Cheat Sheet - GitHub Shortcuts section](appendix-b-screen-reader-cheatsheet.md#github-built-in-keyboard-shortcuts). + +1. Navigate to your comment (`3` to jump to comments) +2. Find the "..." (ellipsis) menu button near your comment +3. Press `Enter` on "Edit" from that menu +4. The comment turns into a text area - switch to Focus Mode +5. Make your changes +6. Tab to "Update comment" button → Enter + +### Learning Cards: Leaving a Comment + +**Screen reader users:** +- Press `D` to jump to the "Add a comment" landmark, which places focus near the text area; then Enter Focus Mode to start typing +- Use `Ctrl+Enter` to submit your comment directly from inside the text area -- this avoids having to Tab through the formatting toolbar to find the Comment button +- To quote someone's text in your reply, select the text in Browse Mode (`Shift+Arrow`), then press `R`; GitHub inserts it as a blockquote in the comment box automatically + +**Low-vision users:** +- The comment text area expands as you type and is full-width at high zoom, making it easy to target; use `Ctrl+Enter` to submit without hunting for the Comment button +- Use the Preview tab next to Write to check your Markdown formatting in rendered form before posting; bold, code blocks, and links are much easier to proofread there +- Keyboard formatting shortcuts (`Ctrl+B` for bold, `Ctrl+E` for inline code) work inside the text area and save time over clicking small toolbar icons + +**Sighted users:** +- The formatting toolbar above the text area offers bold, italic, code, link, and list buttons; hover for tooltips showing the keyboard shortcut for each +- Use the `R` shortcut to quote selected text -- it creates a blockquote in your reply, making threaded conversations much easier to follow +- The Close with comment option (dropdown arrow on the Close button) lets you leave a final note and close the issue in a single action + + +## Filing a New Issue + +### Navigating to New Issue + +
    +Visual / mouse users + +From the Issues list page, click the green **New issue** button in the top-right of the issue list. If the repository has templates, a template picker page appears - click **Get started** next to the template that fits your needs, or click **Open a blank issue** to skip templates. + +
    + +
    +Low vision users (zoom, high contrast) + +The green **New issue** button is in the top-right of the issue list page. At high magnification: + +- At 200%+ zoom, the button may move below the search bar or wrap to its own line. It remains a prominent green button. +- If the repository has issue templates, a template picker page appears with each template as a card. Template descriptions may truncate at high zoom. Hover over a truncated description for the full text. +- The **Get started** button next to each template is small but uses standard link styling. Press `Tab` to move between templates and their Get started buttons. +- **Open a blank issue** link appears at the bottom of the template list. At high zoom, scroll down to find it. +- In Windows High Contrast mode, the New issue button uses the system button colors and the template cards have visible borders. + +
    + +
    +Screen reader users (NVDA / JAWS - Windows) + +From the Issues list: + +1. Press `K` to navigate links and find the "New issue" button/link +2. Press `Enter` +3. If a template picker appears: press `3` to navigate template names, read the description below each, then press `Enter` on "Get started" for the right template - or find "Open a blank issue." link if no template fits + +
    + +
    +Screen reader users (VoiceOver - macOS) + +From the Issues list: + +1. Quick Nav `B` or `VO+U` → Buttons to find the "New issue" button +2. `VO+Space` to activate it +3. If a template picker appears: Quick Nav `H` or `VO+Cmd+H` to navigate template names, then `VO+Space` on "Get started" for the right template - or Quick Nav `K` to find the "Open a blank issue" link + +
    + +### Filling Out the Issue Form + +The issue form has these fields (order may vary depending on the template): + +#### Title field + +1. Find the Title input field (`F` or by landmark) +2. Focus Mode → type a clear, specific title +3. Good title: "Screen reader announces wrong element count on Issues list with 50+ items" +4. Bad title: "Bug with screen reader" + +#### Description / Body field + +1. Tab to the body text area +2. Focus Mode → type using the Markdown template provided +3. If no template, use this structure: + +```markdown +## What happened + +Describe what you observed. + +## What I expected + +Describe what should have happened. + +## How to reproduce + +1. Step one +2. Step two +3. Step three + +## Environment + +- Screen reader: [NVDA 2025.3.3 / JAWS 2026 / VoiceOver macOS Sonoma] +- Browser: [Chrome 124 / Firefox 125 / Safari 17] +- OS: [Windows 11 / macOS 14] +- GitHub interface: [Modern experience (default since Jan 2026) / Classic experience] + +## Additional context + +Any other information, screenshots (with alt text), or links. +``` + +### Assigning labels from the sidebar + +> **See also:** [Chapter 09: Labels, Milestones, and Projects](09-labels-milestones-projects.md) covers the full label and milestone system. + +While the form is open, the sidebar has dropdowns for Labels, Assignees, and Milestone. + +
    +Visual / mouse users + +In the right sidebar, click the gear icon () next to **Labels**. A dropdown opens - click a label to select it. Click outside to close. Repeat for **Assignees** and **Milestone**. + +
    + +
    +Screen reader users (NVDA / JAWS - Windows) + +1. `Tab` away from the text area (or press `Escape` to leave Focus Mode) +2. Navigate to the sidebar - press `H` to find "Labels" heading +3. Press `Enter` on the Labels gear/button +4. Dropdown opens → `↑/↓` to navigate labels +5. `Enter` to select/deselect +6. `Escape` to close (selections save automatically) + +
    + +
    +Screen reader users (VoiceOver - macOS) + +1. `VO+Shift+Up` to stop interacting with the text area +2. `VO+U` → Headings to find the "Labels" heading in the sidebar +3. `VO+Space` on the Labels gear/button to open the dropdown +4. `VO+Down` or arrow keys to navigate labels +5. `VO+Space` to select/deselect +6. `Escape` to close (selections save automatically) + +
    + +### Submitting the issue + +1. Tab to "Submit new issue" button +2. Press `Enter` + +
    +GitHub CLI (gh) alternative - filing a new issue + +Create an issue from your terminal: + +```bash +# Interactive: prompts for title, body, labels, and assignees +gh issue create + +# Inline: provide everything on the command line +gh issue create --title "Screen reader announces wrong count on Issues list" \ + --body "## What happened\n\nThe count says 14 but only 12 issues are visible." \ + --label "bug,accessibility" \ + --assignee @me + +# Use a template (if the repo has issue templates) +gh issue create --template "bug_report.md" +``` + +The interactive mode walks you step-by-step through title, body (opens your editor), labels, and assignees - fully usable from a terminal with a screen reader. + +
    + +### Learning Cards: Filing a New Issue + +
    +Screen reader users + +- After pressing "New issue," if a template picker appears, press `3` to jump between template names; each has a "Get started" link next to it +- In the title field, type at least 12 characters for a meaningful title; press `Tab` to move to the body field +- Press `Ctrl+Enter` from inside the body text area to submit the issue without needing to find the Submit button + +
    + +
    +Low vision users + +- The green "New issue" button is in the top-right of the Issues list page; at 200%+ zoom it may wrap below the search bar +- Template cards (if the repo uses them) show truncated descriptions at high zoom; hover over them for the full text +- The sidebar dropdowns for Labels, Assignees, and Milestone are gear icons that may be small at high zoom; they open searchable dropdown panels + +
    + +
    +Sighted users + +- The new issue form has a Title field at the top and a large Body text area below; a formatting toolbar (bold, italic, code, etc.) appears above the body +- The Write/Preview tabs above the body let you toggle between editing and rendered Markdown views +- Sidebar options (Labels, Assignees, Milestone) appear to the right of the body field; click the gear icon next to each to open a dropdown + +
    + +### Tool Cards: File a New Issue + +**github.com (browser):** +1. Navigate to the repository's **Issues** tab (or press `G` then `I`). +2. Click **New issue**, choose a template or blank issue. +3. Fill in the title and description, then click **Submit new issue**. + +**github.dev (web editor):** +Not available -- issues are managed through the repository's Issues tab, not the code editor. + +**VS Code Desktop (GitHub Pull Requests extension):** +1. Open the **GitHub** panel in the sidebar. +2. Under **Issues**, click the **+** icon to create a new issue. +3. Fill in the title and body, then click **Create**. + +**GitHub Desktop:** +Not directly supported. Click **Repository > View on GitHub** to open the browser, then file the issue there. + +**Git CLI / GitHub CLI:** +```bash +gh issue create --title "Your title" --body "Description here" +# Or interactively: +gh issue create +``` + + +## Cross-Referencing Issues + +Linking issues and PRs to each other creates a trail of context that helps everyone understand the project's history. + +### Closing keywords in PR descriptions or issue comments + +When you type these phrases in a PR description or comment (followed by an issue number), GitHub creates a connection: + +| Keyword | Effect on merge | +| --------- | ---------------- | +| `Closes #42` | Closes issue #42 when the PR merges | +| `Fixes #42` | Same - typically for bugs | +| `Resolves #42` | Same - general use | +| `refs #42` | Creates a reference without auto-closing | +| `cc @username` | Notifies the person | + +### Mentioning another issue in a comment + +Simply type `#` followed by a number anywhere in a comment body. GitHub autocompletes with a dropdown of matching issues and PRs: + +```text +Step 1: Type # in the comment box (Focus Mode) +Step 2: A dropdown appears with issues and PRs +Step 3: ↑/↓ to navigate, or type more numbers to filter +Step 4: Enter to insert the reference +``` + +### Cross-repo references + +`owner/repo#42` - references issue #42 in a different repository. + +### Learning Cards: Cross-Referencing Issues + +**Screen reader users:** +- Type `#` in any comment body to trigger GitHub's autocomplete dropdown; press `Down Arrow` to browse matching issues and `Enter` to insert the reference link +- Use `Closes #42` (not just `#42`) in PR descriptions so GitHub automatically closes the issue on merge; your screen reader will confirm the link is created in the PR timeline +- Cross-references appear as timeline events on the linked issue; navigate with `H` to find "mentioned this issue" entries to trace the conversation history + +**Low-vision users:** +- Cross-reference links (`#42`) render as colored, clickable links in both issue bodies and PR descriptions; at high zoom they remain inline with surrounding text +- The autocomplete dropdown triggered by `#` may overlap content at high magnification; type additional digits to narrow results and reduce dropdown size +- Back-links appear automatically on the referenced issue's timeline, so you can verify the connection was created by visiting either side + +**Sighted users:** +- Use `Closes #42`, `Fixes #42`, or `Resolves #42` in PR descriptions for auto-closing on merge; `refs #42` creates a reference without auto-close, useful for "related but not solved" links +- GitHub's autocomplete (`#` then type) searches both issue titles and numbers, so you can find issues by keyword without memorizing numbers +- Cross-repo references use the format `owner/repo#42` -- useful when your PR in one repository fixes a bug tracked in another + + +## Sub-Issues - Parent and Child Relationships + +**Sub-issues** (released 2025) let you nest issues inside a parent issue to break large work into tracked pieces. A "parent" issue contains a list of child issues; each child is a full issue with its own discussion, labels, and assignees. + +### When to Use Sub-Issues + +| Use case | Example | +| ---------- | --------- | +| Large feature broken down | Parent: "Redesign navigation"; Children: "Keyboard nav," "Screen reader nav," "Mobile nav" | +| Epic tracking | Parent: "WCAG 2.1 AA compliance"; Children: one issue per failing criterion | +| Release milestone | Parent: "v2.0 release"; Children: every required PR/fix | + +### Creating a Sub-Issue + +From any open issue: + +```text +1. Open the parent issue page +2. Scroll to (or H-navigate to) the "Sub-issues" section in the issue body/sidebar +3. Tab to "Add sub-issue" button → Enter +4. Type the issue number or title to search +5. Select the issue from the dropdown → Enter to link + Or: select "Create new issue" to create and link in one step +``` + +**Screen reader note:** The sub-issues section is announced as a region. After linking, the child issue appears as a list item with a checkbox showing its open/closed state. Tab through to read each child's title and status. + +### Reading Sub-Issues on a Parent Issue + +```text +H → "Sub-issues" heading +↓ → list of linked child issues +Each item: [checkbox state] [issue title] [#number] [open/closed badge] +Tab → "Add sub-issue" button (if you have write access) +``` + +**Progress indicator:** The parent issue shows a completion bar (e.g., "3 of 7 completed") based on how many child issues are closed. Screen readers announce this as a progress region. + +### Viewing a Child Issue's Parent + +Every child issue shows a "Parent issue" link near the top of the page (above the description). Navigate with `H` or links (`K`) to find it. + +### Sub-Issues vs. Task Lists + +| Feature | Task list checkboxes | Sub-issues | +| --------- | --------------------- | ------------ | +| Location | Issue description (Markdown) | Sidebar/section (structured data) | +| Each item is | Text line + checkbox | A full GitHub issue | +| Tracked in Projects | No (checkbox only) | Yes (each child tracks independently) | +| Cross-repo | No | Yes | +| Best for | Quick checklists in one issue | Multi-issue work tracking | + +> **Workshop tip:** If you are working on a feature that requires multiple PRs or involves several team members, ask the maintainer to create a parent issue. You can then claim individual child issues without one person owning the whole feature. + +### Learning Cards: Sub-Issues + +**Screen reader users:** +- The sub-issues section is announced as a region; press `H` to navigate to the "Sub-issues" heading, then arrow down through the list where each child announces its checkbox state, title, and open/closed badge +- The parent issue shows a progress indicator ("3 of 7 completed") announced as a progress region; listen for this after the sub-issues heading to gauge overall status +- Every child issue includes a "Parent issue" link near the top of its page; navigate with `K` (links) to find it and jump back to the parent quickly + +**Low-vision users:** +- The completion progress bar on the parent issue uses color to show progress; in high-contrast mode, completed vs. remaining segments use distinct system colors +- At high zoom, the "Add sub-issue" button may wrap below the sub-issues list; Tab past the last child item to reach it +- Each child issue's open/closed badge uses both color and text ("Open" or "Closed"), so status is readable without relying on color alone + +**Sighted users:** +- Sub-issues appear as a checklist with a progress bar on the parent issue; each child links directly to its own issue page with full discussion and labels +- Use sub-issues instead of Markdown task-list checkboxes when each item needs its own assignee, labels, or cross-repo tracking -- sub-issues are structured data, not just text +- Creating a sub-issue from the parent's "Add sub-issue" button auto-links the new issue; you can also link existing issues by searching their number or title + + +## Managing Issues (for Maintainers and Triagers) + +### Closing an issue + +
    +Visual / mouse users + +Scroll to the bottom of the issue page. Click the **Close issue** button next to the comment box. Optionally type a closing comment first. If you want to record a reason, click the dropdown arrow on the button and choose **Close as completed** or **Close as not planned**. + +
    + +
    +Screen reader users (NVDA / JAWS - Windows) + +1. **Keyboard shortcut (fastest):** Navigate to the comment text area (`D` → "Add a comment" landmark), switch to Focus Mode, then press `Ctrl+Shift+Enter` to close the issue +2. **Button approach:** `Tab` to the "Close issue" button (at the bottom of the page, near the comment box) and press `Enter` +3. Optionally leave a closing comment first + +
    + +
    +Screen reader users (VoiceOver - macOS) + +1. **Keyboard shortcut (fastest):** `VO+U` → Landmarks → "Add a comment", interact with the text area (`VO+Shift+Down`), then press `Cmd+Shift+Return` to close the issue +2. **Button approach:** Quick Nav `B` or `Tab` to find the "Close issue" button, then `VO+Space` +3. Optionally leave a closing comment first + +
    + +
    +GitHub CLI (gh) alternative - closing and reopening + +Close or reopen an issue from your terminal: + +```bash +# Close an issue +gh issue close 42 + +# Close with a reason +gh issue close 42 --reason "completed" +gh issue close 42 --reason "not planned" + +# Close with a comment +gh issue close 42 --comment "Fixed in PR #45." + +# Reopen a closed issue +gh issue reopen 42 +``` + +
    + +### Reopening a closed issue + +If an issue is Closed, the "Close issue" button becomes "Reopen issue" - navigate and activate to reopen. + +### Assigning an issue + +From the issue sidebar: + +1. Navigate to "Assignees" heading (`3` or `H`) +2. Activate the gear/plus button +3. Type a username in the search field +4. Select from the dropdown + +
    +GitHub CLI (gh) alternative - assigning and labeling + +Manage assignments and labels from your terminal: + +```bash +# Assign yourself +gh issue edit 42 --add-assignee @me + +# Add labels +gh issue edit 42 --add-label "accessibility,in progress" + +# Remove a label +gh issue edit 42 --remove-label "needs triage" + +# Set a milestone +gh issue edit 42 --milestone "Hackathon Day 1" +``` + +
    + +### Changing labels + +From the issue sidebar: + +1. Navigate to "Labels" heading +2. Activate the gear button +3. Select/deselect labels from the dropdown +4. Press Escape to save + +### Transferring or deleting an issue + +Available from the "..." (ellipsis) button at the top of the issue - navigate buttons with `B` to find it. + +### Learning Cards: Managing Issues + +**Screen reader users:** +- Close an issue instantly with `Ctrl+Shift+Enter` from the comment text area (Focus Mode) -- no need to Tab to the Close button +- The sidebar sections (Assignees, Labels, Milestone) each have their own heading; press `H` or `3` to jump between them, then activate the gear icon to open each dropdown +- Use `gh issue edit 42 --add-label "accessibility" --add-assignee @me` to batch-update labels and assignments from the terminal without navigating sidebar controls + +**Low-vision users:** +- Sidebar controls (Assignees, Labels, Milestone) are narrow at default width; at high zoom they stack vertically and each dropdown opens a searchable overlay that is easier to read +- The Close issue button turns green and its label changes to "Reopen issue" once closed; in high-contrast mode, both states use distinct system colors +- Type in the search field inside each sidebar dropdown (Labels, Assignees) to filter long lists rather than scrolling through all options at high magnification + +**Sighted users:** +- The issue sidebar on the right contains Assignees, Labels, Projects, and Milestone in collapsible sections; click the gear icon next to each to open the edit dropdown +- Use the dropdown arrow on the Close button to choose "Close as completed" vs. "Close as not planned" -- this distinction helps with project tracking and search filtering +- The "..." menu at the top of any issue provides Transfer, Pin, Lock, and Delete options for repository maintainers + + +## The "good first issue" Label - Your Entry Point + +When looking for your first open source contribution: + +1. Navigate to any project's Issues tab +2. Filter by label: type `is:open label:"good first issue"` in the search +3. Read through issues until you find one in your area of interest +4. Comment on the issue: "Hi, I'd like to work on this. Can I be assigned?" +5. Wait for a maintainer to respond and assign you before starting work + +**Remember:** It's respectful to ask before starting. Maintainers juggle many discussions and need to know who is working on what to avoid duplicated effort. + +### Learning Cards: The "good first issue" Label + +**Screen reader users:** +- Use the filter query `is:open label:"good first issue"` in the search bar to jump directly to beginner-friendly issues; `gh issue list --label "good first issue"` does the same in the terminal +- Before claiming an issue, read existing comments to check whether someone else has already been assigned; listen for "assigned to" in the sidebar metadata +- When you comment to claim an issue, include a sentence about your approach so the maintainer can give early feedback before you start coding + +**Low-vision users:** +- The "good first issue" label renders with a distinct background color (typically light purple or teal); in high-contrast mode it uses system highlight colors with readable text +- Filter results may include issues with multiple labels stacked together; at high zoom, labels wrap to a second line but remain readable +- Bookmark the filtered URL (`/issues?q=is:open+label:"good first issue"`) in your browser for one-click access to beginner issues across your favorite repositories + +**Sighted users:** +- The "good first issue" label is a GitHub convention recognized across the ecosystem; many projects also use "help wanted" for intermediate tasks +- Always comment before starting work -- even if unassigned -- to avoid duplicating effort with another contributor who may already be working quietly +- Read the issue's linked PR history (if any) to see whether previous attempts were made and why they were closed; this saves you from repeating known dead ends + + +## Accessibility-Specific Issue Writing Tips + +When filing accessibility bugs, these details help maintainers reproduce and fix the problem: + +1. **Screen reader and version** - "NVDA 2025.3.3" not just "screen reader" +2. **OS and version** - "Windows 11 22H2" +3. **Browser and version** - "Chrome 124.0.6367.82" +4. **GitHub interface** - "Modern experience (default since Jan 2026)" or "Classic experience (opted out)" +5. **What was announced** - quote the exact text your screen reader spoke +6. **What should have been announced** - describe the expected behavior +7. **ARIA issue if known** - e.g., "The button has no accessible name" +8. **Steps to reproduce** - numbered, step-by-step +9. **Frequency** - "This happens every time" vs "intermittent" + +### Example of a well-filed accessibility issue + +```text +Title: Issues list does not announce label filtering results to screen readers + +## What happened +When I apply a label filter on the Issues list using the Labels dropdown, +the filtered list updates visually but NVDA does not announce that the +results changed or how many items are now shown. + +## What I expected +After filtering, the screen reader should announce something like +"14 issues open, filtered by label: accessibility" or a live region +update indicating the results changed. + +## How to reproduce +1. Navigate to any repo's Issues tab +2. Press B to navigate to the "Label" filter button +3. Press Enter to open the dropdown +4. Select the "accessibility" label +5. Press Escape to close +6. Notice: no announcement that filtering has been applied + +## Environment +- Screen reader: NVDA 2025.3.3 (with NVDA+Chrome) +- Browser: Chrome 124.0.6367.82 +- OS: Windows 11 22H2 +- GitHub interface: Modern experience (default since Jan 2026) + +## Additional context +JAWS 2026 also does not announce. VoiceOver on macOS Sonoma with +Safari 17 does announce "List updated" when filtering is applied, +so the macOS behavior appears correct. +``` + +### Learning Cards: Accessibility-Specific Issue Writing + +**Screen reader users:** +- Always quote the exact text your screen reader announced in the issue body; wrap it in a fenced code block so readers know it is literal output, not your description +- Include your screen reader name and version (e.g., "NVDA 2025.3.3") plus browser and OS; this lets maintainers reproduce with the same toolchain +- Test with a second screen reader or browser if possible and note the results -- "Also fails in JAWS 2026 with Chrome; works in VoiceOver with Safari" dramatically narrows the debugging scope + +**Low-vision users:** +- When filing zoom or contrast bugs, state your exact zoom level and whether you use Windows High Contrast, macOS Increase Contrast, or a browser extension +- Screenshots are powerful evidence; annotate them (circle the problem area, add a text callout) and always include alt text describing what the screenshot shows +- Note whether the issue occurs only at certain zoom levels or viewport widths; a bug at 400% that disappears at 200% points to a CSS breakpoint problem + +**Sighted users:** +- Even if you do not use assistive technology, you can file accessibility issues by testing with keyboard-only navigation (Tab, Enter, Escape) and noting where focus is lost or trapped +- Include the ARIA role or attribute involved if you can identify it from browser DevTools (e.g., "The button has `role=presentation` and no accessible name") +- Link to the relevant WCAG success criterion when possible (e.g., "Fails WCAG 2.1 SC 1.3.1 Info and Relationships"); this gives maintainers a clear standard to design against + + +## Writing Effective Issues + +> **See also:** [Appendix N: Advanced Search](appendix-n-advanced-search.md) covers search qualifiers to find existing issues before filing a new one. + +A well-written issue saves everyone time -- the maintainer who reads it, the contributor who fixes it, and the future searcher who finds it six months later. This section gives you reusable templates for the two most common issue types and a set of principles that apply to every issue you file. + +### Bug Report Structure + +A strong bug report answers five questions. Use this template every time you report something broken. + +| Section | What to write | +|---|---| +| **Title** | Follow the formula: "When I [action], [unexpected result] instead of [expected result]" | +| **Steps to Reproduce** | Numbered list -- start from the earliest relevant step | +| **Expected Behavior** | What *should* happen according to documentation or common sense | +| **Actual Behavior** | What *does* happen -- include exact error messages or screenshots | +| **Environment** | OS, browser, screen reader, app version -- anything that might matter | + +The title formula is the most important part. A title like "When I press Enter on the Submit button, nothing happens instead of creating the issue" tells the maintainer exactly what is broken before they even open the issue. + +> **Screen reader tip:** When pasting error messages into the Actual Behavior section, wrap them in a fenced code block (triple backticks). Screen readers will announce "code block" so the listener knows the text is a literal error, not your description. + +**Steps to Reproduce matter more than you think.** Maintainers cannot fix what they cannot recreate. Number every step, starting from a clean slate -- "Open the repository" is better than "Go to the page." Include what you clicked, what keyboard shortcut you pressed, and what happened after each step. + +### Feature Request Structure + +Feature requests work best when they focus on the *problem* before jumping to the solution. Use this four-part structure: + +1. **Problem statement** -- Describe the pain point. What are you trying to do, and why is it hard or impossible right now? +2. **Proposed solution** -- Your best idea for fixing the problem. Be specific enough to discuss, but hold it loosely. +3. **Alternatives considered** -- Other approaches you thought about and why they fell short. This shows you have done your homework. +4. **Who benefits** -- Name the audience. "Screen reader users navigating large repositories" is more compelling than "everyone." + +A feature request that starts with "I want a dark mode toggle" is weaker than one that starts with "Low-vision users report eyestrain after 20 minutes because the current theme has insufficient contrast." The second version gives maintainers something to design around. + +### General Issue Writing Principles + +These rules apply to every issue -- bugs, features, questions, and everything in between. + +**One issue per problem.** If you discovered two bugs during the same session, file two separate issues. Combining them makes it impossible to close one without the other and clutters the conversation. + +**Write searchable titles.** Future contributors will search before filing. "Bug with button" will never surface in a search for "Submit button unresponsive on Safari." Front-load the title with the specific component or action. + +**Include context, not assumptions.** Instead of "The API is broken," write "The `/repos` endpoint returns a 403 when I pass a valid token." Let maintainers draw their own conclusions from the evidence you provide. + +**Link related issues.** If your bug might be connected to issue #42, mention it: "This might be related to #42." GitHub automatically creates a back-link, building a web of context that helps everyone. You will learn more about cross-referencing in [Chapter 6](06-working-with-pull-requests.md). + +| Principle | Bad example | Good example | +|---|---|---| +| One issue per problem | "The button is broken and also the logo is wrong" | Two separate issues, each with its own title | +| Searchable title | "Help needed" | "Keyboard focus lost after closing modal dialog" | +| Context over assumptions | "Nothing works" | "After upgrading to v2.3, the dashboard returns a blank page on Firefox 124" | +| Link related issues | (no mention) | "Possibly related to #42 -- same component, different trigger" | + +### Before and After: A Vague Issue vs. a Clear Issue + +**Vague issue (hard to act on):** + +> **Title:** Bug +> +> It doesn't work. I tried clicking and nothing happened. Please fix. + +The maintainer has to ask: What doesn't work? Where did you click? What browser? What did you expect? Every follow-up question costs a round-trip of waiting. + +**Clear issue (ready to fix):** + +> **Title:** When I press Enter on the "New issue" button, nothing happens instead of opening the issue form +> +> **Steps to Reproduce:** +> 1. Navigate to github.com/org/repo +> 2. Press `G` then `I` to go to the Issues tab +> 3. Tab to the "New issue" button +> 4. Press `Enter` +> +> **Expected:** The new issue form opens. +> +> **Actual:** The page does not respond. No error in the console. +> +> **Environment:** Windows 11, Firefox 128, JAWS 2025 + +The maintainer can reproduce this in under a minute. No follow-up questions needed -- the fix can start immediately. + +> **Screen reader tip:** You can use the issue template feature in GitHub to pre-fill these sections automatically. If the repository provides templates, your screen reader will announce each section heading as you Tab through the form. You will set up your own issue templates in [Chapter 17](17-issue-templates.md). + +### Learning Cards: Writing Effective Issues + +
    +Screen reader users + +- Use fenced code blocks (triple backticks) when pasting error messages or screen reader output; your screen reader announces "code block" so listeners know the text is literal, not description +- When writing "Steps to Reproduce," type each step as a numbered Markdown list item (`1.`, `2.`, etc.) so screen readers announce "list with N items" +- Type `#` in the comment body to trigger issue autocomplete; press `Down Arrow` to navigate matching issues and `Enter` to insert a cross-reference link + +
    + +
    +Low vision users + +- Use the Preview tab (next to Write) to check your Markdown rendering before submitting; headings, bold text, and code blocks are much easier to proofread in rendered form +- Screenshots with alt text are valuable evidence; add them with the image button in the formatting toolbar or drag-and-drop into the body field +- Keep paragraphs short (3-4 sentences max) so the issue is scannable at high zoom without excessive scrolling + +
    + +
    +Sighted users + +- A well-structured issue uses H2 headings (##) for major sections: What happened, Expected, How to reproduce, Environment +- GitHub renders Markdown tables in issue bodies; use a table to compare expected vs. actual behavior side by side +- The title appears in issue lists, email notifications, and search results; front-load it with the specific component or action for discoverability + +
    + + +## Try It: File Your First Issue + +**Time:** 3 minutes | **What you need:** Browser, signed in to GitHub + +Go to the Learning Room repository and file a real issue: + +1. Navigate to the Issues tab (press `G` then `I` in Focus Mode) +2. Find and activate the "New issue" button (`K` to links, or `Tab` to it) +3. In the title field, type: **"Introduce myself - [Your Name]"** +4. In the description, write 2-3 sentences: who you are, what screen reader you use, and one thing you're hoping to learn today +5. Press `Ctrl+Enter` to submit (or Tab to the Submit button and press `Enter`) + +**You're done.** You just filed your first GitHub issue. Go read someone else's introduction and leave a friendly comment - press `3` to jump between issue titles on the Issues list. + +> **What success feels like:** Your issue is live. Other participants can see it. You just contributed to a real repository - and it took less than three minutes. + +### Learning Cards: Filing Your First Issue + +**Screen reader users:** +- After pressing `Ctrl+Enter` to submit, listen for the page reload; GitHub navigates to your new issue page where the title is the first heading -- press `1` to confirm it matches what you typed +- Navigate the issue list with `3` (heading level 3) to jump between issue titles; this is faster than arrowing through every element on the page +- If the template picker appears, use `Tab` and `Enter` to select "Open a blank issue"; template names are announced as link text + +**Low-vision users:** +- The "New issue" button is prominent and green on the Issues list page; at high zoom it remains visible near the top of the page and does not collapse into a menu +- The title field is full-width and the body field expands as you type; both are easy to locate and target at any zoom level +- After submitting, your new issue page shows your avatar, title, and description in high-contrast-friendly layout; verify the content rendered correctly before moving on + +**Sighted users:** +- Your issue immediately appears at the top of the Issues list; the green "Open" badge confirms it was created successfully +- Read a few other students' introduction issues and leave a comment to practice the commenting workflow from the Leaving a Comment section +- Notice how the issue number (e.g., #150) is auto-assigned and appears in the URL and page title; you will use this number for cross-references later + + +> ### Day 2 Amplifier - Accessibility Agents: `@issue-tracker` +> +> **File, read, comment on, and triage real issues manually before using any agent.** If you have not done the triage work yourself - reading descriptions, assigning labels, identifying duplicates - you cannot evaluate whether an agent's priority scoring is correct. The skill must exist before the amplifier is useful. +> +> Once you have mastered manual issue management: +> +> - **In VS Code** - `@issue-tracker find open issues labeled good-first-issue` searches cross-repository with community sentiment scoring, release-awareness prioritization, and batch-reply capability across every repo you have access to +> - **In your repo** - The issue templates in `accessibility-agents/.github/ISSUE_TEMPLATE/` structure both human filing and automated triage; fork [accessibility-agents](https://github.com/Community-Access/accessibility-agents) and that structure travels into any project you lead +> - **In the cloud** - GitHub Agentic Workflows triage new issues the moment they are opened: applying labels, posting first-response comments, adding to Project boards - the same triage actions you practiced manually today, running at scale +> +> *Today you are the triage engine. On Day 2, you understand the engine well enough to direct it.* + + +> **Challenge Time:** It's time for the real deal. Go to the [Challenge Hub](CHALLENGES.md) and complete **Challenge 2: File Your First Issue** and **Challenge 3: Join the Conversation**. When Aria the bot replies to you, she will tell you when it's time to move to [Chapter 06: Working with Pull Requests](06-working-with-pull-requests.md). + +--- + + +*Next: [Chapter 06: Working with Pull Requests](06-working-with-pull-requests.md)* +*Back: [Chapter 04: The Learning Room](04-the-learning-room.md)* +*Related appendices: [Appendix N: Advanced Search](appendix-n-advanced-search.md) | [Appendix V: GitHub Mobile](appendix-v-github-mobile.md)* + + + + diff --git a/admin/qa-bundle/docs/06-working-with-pull-requests.md b/admin/qa-bundle/docs/06-working-with-pull-requests.md new file mode 100644 index 0000000..c58eeea --- /dev/null +++ b/admin/qa-bundle/docs/06-working-with-pull-requests.md @@ -0,0 +1,1636 @@ +# Working with Pull Requests +> +> **Listen to Episode 6:** [Working with Pull Requests](../admin/PODCASTS.md) - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. + +> **Related appendices:** [Appendix C: Markdown Reference](appendix-c-markdown-reference.md) | [Appendix B: Screen Reader Cheat Sheet](appendix-b-screen-reader-cheatsheet.md) +> **Authoritative sources:** [GitHub Docs: About pull requests](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) | [GitHub Accessibility Guide: Pull Requests](https://accessibility.github.com/documentation/guide/pull-requests/) + + +## Creating, Reviewing, and Merging Pull Requests with a Screen Reader + +> **See also:** [Chapter 15: Code Review](15-code-review.md) covers the full review workflow including multi-file diffs and suggested changes. + +> Pull requests are where your work becomes a contribution. This guide takes you through the full pull request workflow - from opening one to participating in review - using only your keyboard and screen reader. +> +> **Official GitHub Accessibility Guide:** GitHub publishes an NVDA-focused guide for working with pull requests using a screen reader at [Using GitHub Pull Requests with a Screen Reader](https://accessibility.github.com/documentation/guide/pull-requests/). This chapter covers the same material with additional perspectives (VoiceOver, low vision, CLI) and workshop-specific challenges. Use the official guide as a companion reference. +> +> **Screen reader note - New Files Changed Experience:** This guide uses GitHub's improved Files Changed experience, which adds proper ARIA landmark structure to the Files Changed tab, including the file tree and diff navigation. This feature may already be active for your account - it has been broadly rolled out and may no longer appear as a Feature Preview toggle at all. +> +> **To verify:** Activate the **User Menu** button (top-right of any GitHub page) → activate **"Feature preview"** → scan the list for **"New Files Changed Experience"**: +> +> - If listed and the toggle announces **"Pressed"** (or **"Disable"**) - already enabled, no action needed +> - If listed but **not Pressed** (or **"Enable"**) - activate the toggle to enable it +> - If not listed at all - the feature has graduated to the standard interface; it is active automatically +> +> Full step-by-step instructions with per-screen-reader commands are in [Pre-Workshop Setup, Step 4](00-pre-workshop-setup.md#step-4---check-github-feature-preview-settings). +> +> **Browse vs Focus Mode (NVDA):** Use **Browse Mode** (the default) for reading PR conversations, navigating headings, and reviewing diffs. Switch to **Focus Mode** (`NVDA+Space`) only when you need to type in comment boxes or search fields. Switch back to Browse Mode to resume navigation. Maximize your browser window for consistent landmark layout. + + +## Workshop Recommendation (Chapter 6) + +Chapter 6 is the first **PR-validated chapter** where students convert issue work into merge-ready contributions. + +- **Challenge count:** 3 +- **Time per challenge:** under 10 minutes each +- **Evidence:** PR metadata, bot checks, and merged issue linkage +- **Pattern:** small change -> linked PR -> green checks + +### Chapter 6 Challenge Set + +1. **Create one small branch change** - edit a practice file on a new branch. +2. **Open a linked PR** - use the PR template and include `Closes #XX`. +3. **Pass required checks** - respond to bot feedback until all required checks pass. + +> **Branch guidance for Chapter 6:** This is the first chapter where you edit files and create branches. Use one of these two paths: +> +> - **Web editor (recommended for beginners):** When you edit a file on GitHub.com and click "Propose changes," GitHub creates a branch for you automatically. Name it `fix/yourname-issueXX` (for example, `fix/maria-issue42`). +> - **Local Git (if you cloned in Block 0):** Create a feature branch with `git checkout -b fix/yourname-issueXX` from `main`. See the "Local Git Alternative" section below for the full command sequence. +> +> **Do not reuse your `learn/` branch for this short exercise unless your facilitator tells you to.** Chapter 6 works best with a short-lived feature branch such as `fix/yourname-issueXX`, because it teaches the pull request loop without mixing multiple challenges on one branch. + +### Challenge 6.1 Step-by-Step: Create One Small Branch Change + +**Goal:** Edit one of the practice files and save your change on a new branch. + +**Where you are working:** your Learning Room repository on GitHub.com, using the web editor. + +**Before you start:** Open your **assigned Chapter 6.1 challenge issue** (the one titled "Chapter 6.1: Create One Small Branch Change (@yourname)"). The issue description tells you which file to edit and what to fix. + +The Learning Room has three practice files with intentional problems. Your assigned issue points you to one of them: + +The following table summarizes the practice files in the learning-room, what each file contains, and the type of issues to look for. + +| File | What it contains | What to fix | +|------|-----------------|-------------| +| `docs/welcome.md` | Introduction to open source contribution | Three `[TODO]` sections where content is missing | +| `docs/keyboard-shortcuts.md` | Screen reader shortcut reference tables | Intentional errors in shortcut references | +| `docs/setup-guide.md` | Getting-started instructions | Broken links and incomplete steps | + +**Steps using the web editor:** + +1. In your Learning Room repository, navigate to the file specified in your issue. Use the file tree or the "Go to file" button (`T` keyboard shortcut). +2. Open the file and activate the **pencil icon** (Edit this file) button. + - Screen reader users (NVDA/JAWS): Press `B` to navigate buttons, find "Edit this file," and press `Enter`. + - VoiceOver users: Press `VO+U`, open Buttons rotor, find "Edit this file," and press `VO+Space`. +3. The file opens in the web editor. Make your change. For example: + - If your issue is about a `[TODO]` section: replace the `[TODO]` placeholder with the requested content (one to three sentences). + - If your issue is about a broken link: find and correct the URL. + - If your issue is about a shortcut error: find and fix the incorrect value in the table. +4. Keep your change small and focused. Edit only what the issue asks for. + +**Proposing your changes (this creates your branch):** + +5. After editing, activate the **Commit changes** button (green button above the editor). +6. A dialog appears. In the **Branch name** field, type: `fix/yourname-issueXX` (replace `yourname` with your GitHub username, and `XX` with the issue number). +7. Select **Create a new branch for this commit and start a pull request**. +8. Activate **Propose changes**. + +**You are done when:** GitHub shows the "Open a pull request" page. Your file change is saved on a new branch. Continue to Challenge 6.2. + +### Challenge 6.2 Step-by-Step: Open a Linked PR + +**Goal:** Open a pull request + +> **Agentic strategy:** AI agents do not just deploy code directly; they submit pull requests. Learning to edit a file, format it in Markdown, and review a PR today prepares you to audit and approve AI-generated changes tomorrow. Make your Markdown clean and structured, and include the `Closes #XX` line that links to your challenge issue so it closes automatically on merge. + +**Where you are working:** the "Open a pull request" page that appeared after Challenge 6.1 (or navigate to Pull Requests tab and select "Compare and pull request"). + +1. In the **Title** field, write a short description of your change. Examples: + - "Complete the Who Can Contribute section in welcome.md" + - "Fix broken accessibility settings link in setup-guide.md" + - "Correct NVDA modifier key in keyboard-shortcuts.md" +2. In the **Body** field, use the PR template if one is provided. Make sure to include: + - A summary of what you changed and why (at least 50 characters). + - The line `Closes #XX` where `XX` is the number of your **assigned Chapter 6 challenge issue**. +3. Verify the **base branch** is `main` and the **compare branch** is your `fix/yourname-issueXX` branch. +4. Activate the **Create pull request** button. + +**You are done when:** Your PR appears in the Pull Requests list. The bot will begin running checks within about 30 seconds. Continue to Challenge 6.3. + +### Challenge 6.3 Step-by-Step: Pass Required Checks + +**Goal:** Read bot feedback, fix any issues it finds, and get all required checks to pass. + +**Where you are working:** the Conversation tab of your open pull request. + +1. Wait approximately 30 seconds after opening the PR. The bot posts a validation comment. +2. Read the bot comment carefully. It checks: + - That your PR references an issue with `Closes #XX`. + - That your PR description is detailed enough (50+ characters). + - That your changed files are in the `learning-room/` folder. + - Accessibility checks: heading hierarchy, descriptive link text, valid alt text. +3. If the bot reports failures: + - Open the changed file from the **Files changed** tab. + - Activate the pencil icon to edit the file again (directly on your branch). + - Fix the issue the bot identified. + - Commit the fix to the **same branch** (the bot re-runs automatically on each push). +4. Repeat step 3 until all required checks show a green checkmark. +5. When all checks pass, request a review from a peer or the facilitator. + +**You are done when:** The bot comment shows all required checks passed (green checkmarks). Your PR is ready for human review and merge. + +### Expected Outcomes + +- Student opens a focused PR that maps to one issue. +- Student uses `Closes #XX` correctly. +- Student can interpret bot feedback and improve the PR. + +### If You Get Stuck + +1. Confirm your PR includes `Closes #XX` in title or body. +2. Check that changed files are only in `learning-room/`. +3. Open the bot validation comment and resolve one required check at a time. +4. If checks still fail, ask for peer or facilitator review with the exact error message. +5. Finished but not sure you did it right? Compare your work against the [Challenge 6 reference solution](solutions/solution-06-first-pr.md). + +### Learning Moment + +A great PR is small, linked to an issue, and easy to review. Faster feedback builds confidence and momentum. + +### Why this feels achievable + +- Scope is intentionally small. +- Feedback is immediate and specific. +- Success is visible (green checks + closed issue). + + +### About Learning Cards in This Chapter + +This chapter provides learning cards: expandable blocks that offer perspective-specific guidance for different ways of working. Not every card appears at every step. Open the ones that match how you work. + +The following table describes the six learning card types used in this chapter. + +| Card | Who it helps | What it covers | +| --- | --- | --- | +| Visual / mouse | Sighted users navigating with a mouse or trackpad | Click targets, visual cues, layout orientation | +| Low vision | Users with magnification, zoom, or high-contrast themes | Zoom-friendly navigation, finding controls at high magnification, high contrast visibility | +| NVDA / JAWS (Windows) | Screen reader users on Windows | Keystroke sequences, Focus and Browse mode, landmark paths | +| VoiceOver (macOS) | Screen reader users on macOS | VO key sequences, rotor usage, interaction model | +| GitHub.com web | All users working in the browser | Browser-based workflows without local tools | +| CLI (git / gh) | Terminal users on any platform | Git and GitHub CLI commands for PR management | + + +## Local Git Alternative: The Full Branch-Edit-PR Workflow + +
    +If you cloned the learning-room in Block 0 and prefer working locally + +The web editor workflow (pencil button, "Propose changes") is the primary path taught in this chapter. If you cloned the Learning Room in Block 0 and are comfortable in a terminal, here is the local equivalent. This is the same workflow covered in depth in [Chapter 11: Git and Source Control](14-git-in-practice.md). + +**Step 1 - Sync and create a feature branch:** + +```bash +cd ~/Documents/learning-room +git checkout main +git pull origin main +git checkout -b fix/welcome-todos +``` + +**Step 2 - Edit the file in your editor:** + +Open the file in VS Code or your preferred editor: + +```bash +code docs/welcome.md +``` + +Make your changes and save the file. + +**Step 3 - Stage, commit, and push:** + +```bash +git add docs/welcome.md +git commit -m "Complete TODO sections in welcome.md" +git push -u origin fix/welcome-todos +``` + +**Step 4 - Open a pull request:** + +```bash +gh pr create --title "Complete TODO sections in welcome.md" \ + --body "Closes #42" --base main +``` + +Or open interactively: + +```bash +gh pr create +``` + +The GitHub CLI walks you through title, body, base branch, and reviewers. + +**What happens next is identical:** the Learning Room bot validates your PR, posts feedback, and you request a human reviewer - the same as the web workflow. + +> **Tip:** You can also create a named feature branch with `git checkout -b fix/yourname-issueXX` if you prefer that naming convention over the practice branch. + +
    + + +## What Is a Pull Request? + +A pull request (PR) is a proposal to merge changes from one branch into another. When you have: + +- Edited a file directly on GitHub (web editor) +- Made changes in your fork +- Made changes on a feature branch + +...you open a PR to request that those changes be merged into the target branch (usually `main`). + +A PR shows: + +- **What** changed - a diff of every file +- **Why** it changed - your PR description +- **Conversation** - comments, reviews, and discussion +- **Status** - automated checks (CI/CD) and review status + +> **Learning Room connection:** In the Learning Room repository, every hands-on contribution follows this pattern. For example, when you complete Challenge 3 (filling the `[TODO]` sections in `docs/welcome.md`), you open a PR that shows your added content as green `+` lines in the diff, your description explains which TODOs you completed and why, and the validation bot posts automated check results. The scenarios in this chapter use Learning Room files so you can follow along with real content. + + +## Navigating to Pull Requests + +> **Global pull requests dashboard:** GitHub now shows a global pull requests page at [github.com/pulls](https://github.com/pulls) listing all open PRs across every repository you have access to. This is now the **default landing page** when you click "Pull requests" in the top navigation bar (the one above the repository content, not inside a repository). You can opt out in your GitHub settings if you prefer the old behavior. Screen reader path: top navigation region > "Pull requests" link > Enter (or navigate to github.com/pulls directly). + +
    +Visual / mouse users + +Click the **Pull requests** tab in the repository navigation bar. The tab shows the count of open PRs. Click any PR title to open it. + +
    + +
    +Low vision users (zoom, high contrast) + +The **Pull requests** tab is in the repository navigation bar near the top of the page. At 200% browser zoom or higher, the tab bar may wrap to a second line. The tab text includes the open PR count in parentheses. + +- In **Windows High Contrast** mode, the active tab is indicated by a system-colored underline, not just a color change. +- At high magnification, use `Tab` to move through the repository navigation links if the tab bar is hard to target with a pointer. +- Once in the PR list, PR titles are links with standard hover underlines. They remain clickable at any zoom level. + +
    + +
    +Screen reader users (NVDA / JAWS - Windows) + +1. `D` → "Repository navigation" landmark +2. `K` to navigate tabs → "Pull requests, [N] open" +3. `Enter` to open + +
    + +
    +Screen reader users (VoiceOver - macOS) + +1. `VO+U` → Landmarks → navigate to "Repository navigation" +2. Quick Nav `K` or `VO+Right` to navigate tabs → "Pull requests" +3. `VO+Space` to open + +
    + +### From a PR notification + +If you received a notification about a PR, follow the notification link directly to the PR page. + +
    +GitHub CLI (gh) alternative + +List and view pull requests from your terminal: + +```bash +# List open PRs +gh pr list + +# Filter by review status +gh pr list --search "review-requested:@me" + +# View a specific PR in the terminal +gh pr view 42 + +# Open a PR in your browser +gh pr view 42 --web +``` + +**Setup:** Install the GitHub CLI from [cli.github.com](https://cli.github.com) and authenticate with `gh auth login`. See [Appendix D](appendix-d-git-authentication.md) for details. + +
    + +### Learning Cards: Navigating to Pull Requests + +**Screen reader users:** +- Press `D` to jump to the "Repository navigation" landmark, then `K` to reach the "Pull requests" tab link -- this is faster than arrowing through the entire page +- The tab link announces the open PR count ("Pull requests, 7 open"), giving you a quick triage number without opening the list +- From any GitHub page, press `G` then `P` (two sequential key presses in Focus Mode) to jump directly to the repository's Pull Requests tab + +**Low-vision users:** +- The Pull requests tab is in the repository navigation bar near the page top; at 200%+ zoom the tab bar may wrap to a second line, but each tab remains a distinct clickable link +- The open PR count appears in parentheses next to the tab text; zoom into the tab area to read it without opening the list +- Use `Tab` key navigation to step through the repository nav links if pointer targeting is difficult at high magnification + +**Sighted users:** +- Click the **Pull requests** tab in the horizontal navigation bar below the repository name; the badge shows the number of open PRs +- Bookmark the URL pattern `github.com/OWNER/REPO/pulls` to skip navigation entirely +- The active tab is underlined; open PRs are the default view -- use the "Closed" filter link to toggle + + +## The Pull Request List Page + +The PR list works identically to the Issues list: + +- `3` to navigate PR titles (they are h3 headings) +- `I` to navigate list items +- `F` or `E` / `Shift+E` to reach the search/filter field +- Filters work the same as Issues: `is:open`, `author:@me`, `review-requested:@me`, etc. + +> **Screen reader note - PR list semantics:** The PR list does **not** have individual ARIA item containers with per-item semantics. To read a PR's full detail (title, author, labels, status), you must navigate sequentially with `Tab` or arrow keys through the elements for each item. Starting from a PR title link, `Tab` forward to find the author, labels, and review status for that same PR before moving to the next title. +> +> **Hovercards:** Hovercards appear when you hover over usernames and links in the PR list, adding extra verbosity. To reduce this noise: go to your GitHub Profile → Accessibility settings → disable "Show link previews" and similar hover triggers. This makes sequential navigation significantly less cluttered. + + +## Anatomy of a Pull Request Page + +A PR page has three main tabs: + +```text +[PR title - h1] +[State badge: Open / Merged / Closed / Draft] +[Author, base ← compare, timestamp] + +[ Conversation ] [ Commits ] [ Files changed ] + ↑ tab bar landmark + +─── Conversation Tab ──────────────────────────────────────── +[PR description - authored by opener] +[Status checks summary] +[Activity / review thread] + [Review comment - h3] + [Line comments - nested] +[Merge controls (for maintainers)] +[Comment box] + +─── Commits Tab ───────────────────────────────────────────── +[List of commits, grouped by date - h3 for dates] +[Each commit as a list item with SHA, message, author] + +─── Files Changed Tab ──────────────────────────────────────── +[File filter search] +[File tree (left panel)] +[Diff for each file - each file is a heading] +[Line-level comment threads within diffs] +``` + + +## Navigating the PR Tab Bar + +The Conversation, Commits, and Files changed tabs are in a “Pull request navigation tabs” landmark. + +
    +Visual / mouse users + +The three tabs - **Conversation**, **Commits**, and **Files changed** - appear just below the PR title. Click the tab you want. The active tab is underlined. The count on **Files changed** shows how many files were modified. + +
    + +
    +Low vision users (zoom, high contrast) + +The PR tab bar sits just below the PR title and state badge. At high zoom levels: + +- The three tabs (**Conversation**, **Commits**, **Files changed**) may stack or wrap. Each tab remains a distinct clickable link. +- The active tab is distinguished by an underline. In Windows High Contrast mode, the underline uses a system accent color for visibility. +- The **Files changed** tab includes a count (for example, "Files changed 3"). This count is part of the link text, not a separate element. +- If the tabs are hard to click at high magnification, use `Tab` key navigation from the PR title area to reach each tab link sequentially. + +
    + +
    +Screen reader users (NVDA / JAWS) + +1. Press `D` → navigate to “Pull request navigation tabs” +2. Press `←` or `→` arrow keys to move between tab options +3. Press `Enter` to activate a tab + +
    + +
    +Screen reader users (VoiceOver) + +1. `VO+U` → Landmarks → “Pull request navigation tabs” +2. `VO+Right` to move between tabs +3. `VO+Space` to activate + +
    + +Each tab link reads with its name and the count: "Files changed, 3 files changed." + + +## Reading the Conversation Tab + +### PR Description + +1. `2` → navigate to "Description" h2 heading +2. `↓` to read the description +3. Markdown renders as semantic HTML - headings, lists, code blocks are fully accessible + +### Status Checks Section + +Below the description, the status checks summary shows whether automated tests passed. Look for: + +- “All checks have passed” / “Some checks failed” / “Checks pending” +- A “Show all checks” button or link + +
    +Visual / mouse users + +Status checks appear as a coloured banner below the PR description - green tick for passed, red X for failed, yellow spinner for running. Click **Show all checks** to expand the full list. Click a check name to go to its run log. + +
    + +
    +Screen reader users (NVDA / JAWS - Windows) + +1. Press `H` or `2` to find the "Checks" or "Status checks" heading +2. Press `K` to navigate links for individual check names +3. Press `Enter` on a check to see its details + +
    + +
    +Screen reader users (VoiceOver - macOS) + +1. Quick Nav `H` or `VO+Cmd+H` to jump to the "Checks" or "Status checks" heading +2. Quick Nav `K` to navigate check name links +3. `VO+Space` on a check to see its details + +
    + +See [GitHub Actions & Workflows](appendix-q-actions-workflows.md) for full guidance on reading status checks. + +### Review Comments + +Each review comment thread is an h3. Navigate with `3`: + +- Hear the reviewer's username, timestamp, and their review verdict ("approved" or "requested changes") +- Then the body of their review comment +- Then any replies to that comment + +To reply to a review comment: + +```text +Step 1: Navigate to the comment (3) +Step 2: Tab to "Reply…" link/button +Step 3: The reply text area appears - Focus Mode → type your reply +Step 4: Ctrl+Enter to submit +``` + +#### Resolving conversations + +When a review comment has been addressed, you can mark the conversation as resolved: + +1. Navigate to the conversation thread (`3` to jump between comment headings) +2. `Tab` to the end of the thread to find the **"Resolve conversation"** button +3. Press `Enter` to mark it resolved +4. The conversation collapses and shows as "Resolved" + +Resolved conversations are still accessible - they collapse but can be expanded again. This helps both reviewers and authors track which feedback items have been addressed. + +### Learning Cards: Reading the Conversation Tab + +
    +Screen reader users + +- Press `2` to jump between H2 headings: "Description" (the PR body) and "Activity" (the comment thread) +- Press `3` to jump between individual review comments (each is an H3); each announces the reviewer's username, timestamp, and verdict +- Press `D` to jump to the "Add a comment" landmark at the bottom to skip directly to the reply box + +
    + +
    +Low vision users + +- Status checks below the description show green checkmarks (passed), red X marks (failed), or yellow spinners (running); zoom in on this area after opening a PR +- Review comments have a colored left border: green for "Approved," red for "Request changes," grey for "Comment" +- The merge button section at the bottom turns green when all checks pass; it is disabled (greyed out) when checks are pending or reviews are missing + +
    + +
    +Sighted users + +- The Conversation tab has a timeline layout: PR description at the top, status checks below, then comments and events in chronological order +- Review verdicts appear as banners in the timeline: a green banner for Approve, a red banner for Request Changes +- The merge section at the bottom shows which requirements are met (green checkmarks) and which are pending (yellow dots) + +
    + + +## Reading the Commits Tab + +```text +Step 1: Navigate to Commits tab (D → PR tabs → Enter) +Step 2: 3 to navigate date group headings ("Commits on April 20") +Step 3: I to navigate individual commits within a date group +Step 4: Each commit: SHA link, message, author, [Verified] badge if signed +Step 5: Enter on a commit to open its diff +``` + + +## Reading the Checks Tab + +The Checks tab shows the status of automated tests, CI workflows, and other verification processes running on your PR. It helps you verify whether your changes pass all required tests before merging. + +
    +Screen reader users (NVDA / JAWS - Windows) + +1. Navigate to the **"Pull request tabs"** landmark (`D`) +2. Navigate between tab links (`K` or `Tab`) and activate "Checks" +3. Press `D` to jump to the **"check suites"** section - this moves focus to the collapsed details button of the first check +4. Press `B` or `Tab` to navigate between check buttons; each button is labeled with the check's name +5. Press `Enter` or `Space` to expand a check and reveal its logs: + - Navigate through the check steps with `K` or `Tab` + - Activate a step for more details +6. For a summary view: press `D` to navigate to the **"check run summary"** section + +
    + +
    +Screen reader users (VoiceOver - macOS) + +1. `VO+U` -> Landmarks -> "Pull request tabs" -> activate "Checks" +2. `VO+U` -> Landmarks -> navigate to "check suites" section +3. `VO+Right` to move through check buttons, `VO+Space` to expand +4. For summary: `VO+U` -> Landmarks -> "check run summary" + +
    + +### Learning Cards: Reading the Checks Tab + +**Screen reader users:** +- Each check button is labeled with the check's name and its pass/fail state; listen for "success" or "failure" in the ARIA label before expanding the details +- Press `D` to jump between the "check suites" and "check run summary" landmarks to get a high-level pass/fail overview without expanding every check +- If a check fails, expand it and press `K` to navigate step links inside the log -- the failing step is usually labeled with a red X icon described in the accessible name + +**Low-vision users:** +- Passed checks show a green checkmark icon; failed checks show a red X icon; pending checks show a yellow dot -- in Windows High Contrast mode these map to system success/error/warning colors +- At high zoom, each check row may wrap; the icon and check name stay on the first line, while the duration and "Details" link may appear on a second line +- Click the "Details" link next to a failed check to jump to the CI log; failed steps are highlighted with a red background that remains visible in high-contrast themes + +**Sighted users:** +- Scan the Checks tab for a row of green checkmarks (all passed) or spot a red X (failed); the summary banner at the top reads "All checks have passed" or "Some checks were not successful" +- Click any check name to expand its step log inline; failed steps are bolded and marked with a red X so you can skip passing steps quickly +- The "Re-run" button (circular arrow) appears next to each check for maintainers; use it to retry a flaky check without pushing a new commit + + +## Reading the Files Changed Tab + +This is the core of a code review. You will read diffs - the before/after state of every file that changed. + +> **Note:** This guide uses GitHub's improved Files Changed experience. If your Files Changed tab doesn't match these steps, refer to the screen reader verification steps in the prerequisite callout at the top of this chapter - the feature may need to be enabled in Feature Preview, or it may already be active for your account with no action required. + +### File Tree (left panel) + +The file tree lists every changed file. Use it to jump directly to a specific file’s diff. + +
    +Visual / mouse users + +The file tree panel is on the left side of the Files Changed tab. It lists every modified file. Click a filename to scroll the diff view to that file. You can collapse or expand folders by clicking the arrow. Type in the filter box at the top to narrow the file list. + +
    + +
    +Low vision users (zoom, high contrast) + +The file tree panel is on the left side of the Files Changed tab. At 200% zoom or higher: + +- The panel may collapse into a toggle button or hamburger menu. Look for a sidebar toggle icon in the top-left area of the Files Changed tab. +- File names in the tree may be truncated. Hover over a truncated name to see the full path in a tooltip. +- The filter box at the top of the file tree lets you type a filename to narrow the list. This is faster than scrolling through a long file list at high magnification. +- Each file entry shows an icon indicating the change type (added, modified, deleted). In high-contrast themes, these icons use distinct system colors rather than relying on green/red alone. + +
    + +
    +Screen reader users (NVDA / JAWS - Windows) + +1. `D` → navigate to "File tree" region +2. `↑/↓` to navigate the file list +3. `Enter` to jump to that file's diff + +
    + +
    +Screen reader users (VoiceOver - macOS) + +1. `VO+U` → Landmarks → navigate to "File tree" region +2. `VO+Down` to move through the file list +3. `VO+Space` to jump to that file's diff + +
    + +### The Diff for a File + +Each changed file has: + +- A **file heading** (its path, e.g., "src/index.html") - navigable with `3` or `H` +- A **stats line** ("24 additions, 6 deletions") +- The **diff content** - a table where each row is one line of code + +#### Lines in a diff are read as + +- `+ Added line` - line that was added +- `- Removed line` - line that was removed +- `Context line` - unchanged line shown for context + +### Navigating the diff with a screen reader + +
    +Visual / mouse users + +Each file’s diff shows added lines in green and removed lines in red. Scroll the page to read through changes. Unchanged context lines are shown in white/grey. Collapse a file’s diff by clicking the arrow next to its filename heading. Use `Ctrl+F` (browser Find) to search for specific text within visible diffs. + +
    + +
    +Low vision users (zoom, high contrast) + +The diff view uses color-coded backgrounds: green for added lines, red for removed lines, and white or grey for unchanged context. + +**Tips for reading diffs at high magnification:** + +- Enable **Split diff** view (dropdown at the top of Files Changed tab) to see old and new versions side-by-side. At very high zoom, **Unified diff** may be more comfortable because it uses a single column. +- Each line has a `+` or `-` prefix in addition to the color. In Windows High Contrast mode, the color backgrounds are replaced with system contrast colors and the `+`/`-` prefixes remain visible. +- Use `Ctrl+F` (browser Find) to search for specific text within the visible diffs. This is often faster than scrolling through long diffs at high zoom. +- Line numbers appear on the left margin. At extreme zoom levels, these may overlap the code text. Hover over a line number to see the full number in a tooltip. +- To collapse a long diff and reduce visual clutter, click the arrow next to the file heading. + +
    + +
    +Screen reader users (NVDA / JAWS) + +1. `T` to jump to the next diff table +2. Switch to Focus Mode: `Insert+Space` (NVDA) or `Insert+Z` (JAWS) +3. `Ctrl+Alt+↓` to move down one row (next diff line), `Ctrl+Alt+↑` to move up +4. `Ctrl+Alt+→` to read across columns (line number | change type | content) +5. The screen reader reads: “+ Add accessible name to submit button” +6. Collapsed sections contain unchanged code. Focus the expand/disclosure control and activate it (`Enter` or `Space`) to reveal the hidden lines. + +> **Tip:** You can also use `↓` and `↑` in Focus Mode for simpler line-by-line reading when you don’t need column-level detail. Use `NVDA+F7` to get a headings overview of all changed files before diving into individual diffs. + +
    + +
    +Screen reader users (VoiceOver) + +1. `T` or `VO+U` → Tables → select the diff table +2. `VO+Shift+Down` to enter the table +3. `VO+Right/Left` for columns, `VO+Up/Down` for rows + +
    + +### Placing an inline comment on a diff line + +
    +Visual / mouse users + +Hover over any line in the diff - a blue `+` button appears on the left margin. Click it to open a comment box for that line. Type your comment, then click **Add single comment** (posts immediately) or **Start a review** (batches the comment with others). To select a range of lines, click and drag across the line numbers on the left. + +
    + +
    +Low vision users (zoom, high contrast) + +The inline comment button (a blue `+` icon) appears on hover near the left margin of each diff line. At high magnification: + +- The `+` button can be small and hard to target. **Keyboard alternative:** `Tab` into the diff line area, then press `Enter` on the focused line to open the comment box. +- Once the comment box opens, it spans the full width of the diff area. At 200% zoom, you may need to scroll down to see the **Add single comment** and **Start a review** buttons below the text area. +- In Windows High Contrast mode, the `+` button uses the system link color rather than blue, and the comment box border uses the system window frame color. + +
    + +
    +Screen reader users (NVDA / JAWS - Windows) + +1. Navigate to the specific line in the diff (using the table navigation above) +2. While focused on that line, a comment button appears - press `Enter` or `Space` to activate it +3. A comment box opens below the line +4. Focus Mode → type your comment +5. `Tab` to **Add single comment** button (instant comment) OR **Start a review** (to batch comments) + +#### Multi-line comment (Windows) + +1. Focus the first line you want to comment on +2. Press `Shift+↓` to extend the selection to additional lines +3. A comment button appears - activate it +4. The comment applies to the full range of selected lines + +
    + +
    +Screen reader users (VoiceOver - macOS) + +1. Navigate to the specific line in the diff (using the table navigation above) +2. While focused on that line, `VO+Space` on the comment button that appears +3. A comment box opens below the line +4. `VO+Shift+Down` to interact with the text area, then type your comment +5. `VO+Shift+Up` to stop interacting, then `Tab` to **Add single comment** and `VO+Space` + +#### Multi-line comment (macOS) + +1. Focus the first line and `Shift+↓` to extend the selection +2. `VO+Space` on the comment button that appears +3. The comment applies to the full range of selected lines + +
    + +### Viewing comments within the diff + +Inline comments appear as expandable threads within the diff table. Navigate to them with `3` (they are h3 headings). Each thread shows the comment, any replies, and a "Reply" button. + +### Learning Cards: Reading the Files Changed Tab + +
    +Screen reader users + +- Press `D` to jump to the "File tree" landmark on the left; use `Up/Down Arrow` to navigate files, `Enter` to jump to that file's diff +- Press `T` to jump to the next diff table; use `Ctrl+Alt+Down Arrow` to walk through diff lines row by row +- Each line is announced with its change type: `+` for additions, `-` for deletions, and context lines with no prefix + +
    + +
    +Low vision users + +- Added lines have a green background; removed lines have a red background; in high-contrast themes, these use bolder system-color shading +- Toggle between Split diff (two-column) and Unified diff (single-column) using the dropdown at the top of the Files Changed tab; Unified is easier at high zoom +- Each file heading shows the path and a summary like "+24 -6"; zoom in on this to quickly assess the scope of changes per file + +
    + +
    +Sighted users + +- The file tree panel on the left lists every changed file; click a filename to scroll the right panel to that file's diff +- Green-highlighted lines are additions; red-highlighted lines are deletions; grey lines are unchanged context +- Hover over any line number in the diff to reveal a blue "+" button for adding an inline review comment + +
    + + +## Opening a Pull Request + +### Tool Cards: Open a Pull Request + +**github.com (browser):** +1. Push your branch, then click the **Compare & pull request** banner (or go to **Pull requests > New pull request**). +2. Set base branch to `main`, compare branch to yours. +3. Fill in the title and description, then click **Create pull request**. + +**github.dev (web editor):** +1. After committing changes, click the **Source Control** icon. +2. Click **Create Pull Request** in the Source Control panel header. +3. Fill in details and submit. + +**VS Code Desktop (GitHub Pull Requests extension):** +1. Press `Ctrl+Shift+P`, type **GitHub Pull Requests: Create Pull Request**. +2. Select base and compare branches. +3. Fill in the title and description, then click **Create**. + +**GitHub Desktop:** +1. After pushing your branch, click **Create Pull Request** in the banner or **Branch > Create Pull Request**. +2. This opens github.com with the PR form pre-filled. + +**Git CLI / GitHub CLI:** +```bash +git push -u origin your-branch +gh pr create --title "Your title" --body "Description" +``` + +### From the web editor workflow (editing a file on GitHub) + +1. You edited a file → GitHub showed a "Propose changes" form +2. You named your branch and activated "Propose changes" +3. GitHub redirected you to the "Open a pull request" page + +### From a fork or feature branch + +
    +Visual / mouse users + +1. Navigate to the repository on GitHub +2. If you recently pushed, a yellow banner “Compare & pull request” appears at the top - click it +3. If no banner appears: click the **Pull requests** tab → click the green **New pull request** button +4. Use the branch dropdowns to choose your **base** branch (what to merge into) and your **compare** branch (your changes) +5. Click **Create pull request** + +
    + +
    +Screen reader users (NVDA / JAWS - Windows) + +1. Navigate to the repository +2. A "Compare & pull request" banner may appear (if you recently pushed) - activate it +3. OR: Navigate to Pull Requests tab → "New pull request" +4. Choose your base branch (what to merge into) and compare branch (your changes) + +
    + +
    +Screen reader users (VoiceOver - macOS) + +1. Navigate to the repository +2. Check for a "Compare & pull request" banner - Quick Nav `B` to find and `VO+Space` to activate it +3. OR: navigate to Pull Requests tab (`VO+U` → Landmarks → Repository navigation) → Quick Nav `B` for "New pull request" +4. Use the branch dropdowns (`VO+Space` to open, arrow keys to select) to choose base and compare branches + +
    + +### Filling out the PR form + +#### Title field + +```text +Step 1: F to navigate to the title field +Step 2: Focus Mode → type a descriptive title +Step 3: Good: "Add keyboard navigation for carousel component" +Step 4: Bad: "Fix bugs" +``` + +#### Description field + +```text +Step 1: Tab to the body text area +Step 2: Focus Mode → type using the PR template (if provided) +``` + +> **Copilot can write your PR description:** If your account has Copilot access, a **"Copilot actions"** button appears in the description toolbar. Activate it to open a menu with options to generate a summary of your changes or an outline of the most important changes in the PR. Screen reader users: `Tab` from the description text area to find the "Copilot actions" button, then press `Enter` to open the menu and `↑/↓` to choose an option. + +If no template, use this structure: + +```markdown +## Summary + +What does this PR change and why? + +## Changes + +- Added `aria-label` to the search button +- Fixed keyboard trap in the modal dialog +- Replaced `
    ` with ` += = = = = = = + +> > > > > > > f e a t u r e / f o r m - i m p r o v e m e n t s +``` + +*(Note: screen readers may spell out the `<` and `>` characters letter by letter - this is normal)* + +### Learning Cards: Resolving Conflicts on GitHub + +
    +Screen reader users + +- After clicking "Resolve conflicts," GitHub opens a text editor; switch to Focus Mode (`NVDA+Space`) and use `Down Arrow` to read line by line through the conflict markers +- After editing, press `Tab` to find the "Mark as resolved" button (top-right of the file); then `Tab` again to "Commit merge" after all files are resolved +- Use `NVDA+F7` to open the Elements List and find the file navigator if there are multiple conflicted files + +
    + +
    +Low vision users + +- The conflict editor is a monospace text editor that may require horizontal scrolling at high zoom; use `Shift+Scroll` for wide lines +- The file list panel on the left shows all conflicted files; at high zoom it may collapse to a toggle icon in the top-left corner +- The "Mark as resolved" button is in the top-right of each file's editor; at 200%+ zoom you may need to scroll right to find it + +
    + +
    +Sighted users + +- The conflict editor highlights your version and the incoming version with different background colors, with the `=======` divider between them +- A file list on the left side lets you jump between conflicted files; a checkmark appears next to each file after you click "Mark as resolved" +- After all files show checkmarks, the green "Commit merge" button becomes available at the top of the editor + +
    + + +## Resolving Conflicts in VS Code (Day 2) + +> **See also:** [Appendix E: Advanced Git](appendix-e-advanced-git.md) covers rebase, cherry-pick, and other advanced conflict resolution strategies. + +VS Code has excellent merge conflict tooling with full screen reader support. This is covered in depth in [Git & Source Control in VS Code](14-git-in-practice.md), but here is an overview: + +### VS Code shows conflicts as + +``` +<<<<<<< HEAD (Current Change) +Your version +======= original -- (3-way merge, if enabled) +Original version before both edits +======= +Incoming version +>>>>>>> branch-name (Incoming Change) +``` + +### VS Code merge conflict actions + +
    +Visual / mouse users + +When your cursor is on a conflict region, VS Code shows **CodeLens action links** above the conflict block in the editor: + +- **Accept Current Change** - keeps your version (HEAD) +- **Accept Incoming Change** - keeps the branch version being merged +- **Accept Both Changes** - keeps both (stacked one after the other) +- **Compare Changes** - opens a side-by-side diff + +Click the link you want. The conflict markers disappear and your chosen content remains. Save the file with `Ctrl+S`. + +
    + +
    +Low vision users (zoom, high contrast) + +VS Code highlights conflict regions with colored background bands: + +- **Current Change** (your version) appears with a green-tinted background +- **Incoming Change** (their version) appears with a blue-tinted background + +In high-contrast themes, these colors map to system theme colors that remain distinguishable. The **CodeLens action links** (Accept Current Change, Accept Incoming Change, Accept Both Changes, Compare Changes) appear as small text links above the conflict block. + +**Tips for comfort at high zoom:** + +- At 200% editor zoom (`Ctrl+=`), the CodeLens links remain clickable. If they feel small, use `Ctrl+Shift+P` and type `Merge Conflict: Accept Current` (or `Incoming`, `Both`) to trigger the same actions from the Command Palette without clicking. +- Enable **Editor, Minimap: Enabled = false** in settings to reclaim horizontal space at high zoom. +- Use `Ctrl+Shift+M` to open the Problems panel. After resolving markers, this panel confirms no remaining conflict errors. +- Use `F8` (Next Problem) to jump between remaining conflict regions across the file without scrolling. + +
    + +
    +Screen reader users (NVDA / JAWS - Windows) + +1. Open the conflicted file +2. Press `↓` to navigate to a conflict marker (`<<<<<<<`) +3. The CodeLens links appear above - press `Tab` to reach them +4. Press `Enter` on your chosen action +5. Save the file (`Ctrl+S`) +6. Stage the resolved file: `Ctrl+Shift+G` → find the file → **Stage changes** +7. Commit the merge + +**GitHub Copilot can help:** With the cursor in a conflict region, open Copilot Chat (`Ctrl+Shift+I`) and type: "Resolve this merge conflict - keep meaningful changes from both sides." Copilot will suggest a resolution that you can review and accept. + +
    + +
    +Screen reader users (VoiceOver - macOS) + +1. Open the conflicted file +2. `VO+Down` or arrow keys to navigate to a conflict marker (`<<<<<<<`) +3. The CodeLens links appear above - `Tab` to reach them +4. `VO+Space` on your chosen action +5. Save the file (`Cmd+S`) +6. Stage the resolved file: `Cmd+Shift+G` → find the file → **Stage changes** +7. Commit the merge + +**GitHub Copilot can help:** With the cursor in a conflict region, open Copilot Chat (`Cmd+Option+I`) and type: "Resolve this merge conflict - keep meaningful changes from both sides." Copilot will suggest a resolution that you can review and accept. + +
    + + +## When You Feel Stuck + +### Ask for help - it's normal + +If you are unsure which version to keep: + +1. Leave a comment on the PR: "I have a merge conflict in `filename.js` and I'm not sure which version to keep - could someone help me understand the intent of these two changes?" +2. Tag the PR author or a maintainer with `@username` + +### Abandon and start fresh (nuclear option) + +If a conflict is severe (the branch diverged a lot from main): + +1. Close the PR without merging +2. Start a new branch from the latest `main` +3. Apply only your intended changes to the new branch +4. Open a new PR + +This is legitimate - not a failure. + +### Learning Cards: When You Feel Stuck + +
    +Screen reader users + +- Leave a PR comment asking for help: press `D` to the "Add a comment" landmark, type your question including the filename and your confusion, then `Ctrl+Enter` to submit +- Use `@username` to tag the PR author or a maintainer so they receive a notification; type `@` and GitHub autocompletes usernames +- If you need to abandon and start fresh, close the PR (Tab to "Close pull request" button), create a new branch from main, and re-apply only your intended changes + +
    + +
    +Low vision users + +- When stuck, scroll to the comment box at the bottom of the PR's Conversation tab and describe which file and which lines are confusing +- The "Close pull request" button is at the bottom of the Conversation tab next to the comment box; closing a conflicted PR is a valid strategy, not a failure +- After starting a new branch, verify you are on the latest main by checking the branch selector in the top-left of the Code tab + +
    + +
    +Sighted users + +- Post a comment on the PR with a screenshot or code snippet showing the conflict you cannot resolve; tag the author with `@username` +- The "Close pull request" button is a red-outlined button at the bottom of the Conversation tab; use it to close and start fresh if the conflict is severe +- When starting over, use the branch dropdown on the Code tab to verify you branched from the latest `main` before re-applying your changes + +
    + + +## Reading a Conflict Message from Git (Command Line Reference) + +If you work locally, `git merge` or `git pull` will say: + +```text +CONFLICT (content): Merge conflict in src/index.html +Automatic merge failed; fix conflicts and then commit the result. +``` + +And `git status` will show: + +```text +both modified: src/index.html +``` + +These are normal outputs. The conflict markers are inserted into the file by Git - open the file and follow the steps above. + +
    +Git CLI alternative - resolving conflicts in the terminal + +Resolve merge conflicts entirely from the command line: + +```bash +# 1. Start the merge that causes the conflict +git merge main + +# 2. See which files have conflicts +git status +# Look for "both modified:" entries + +# 3. Open each conflicted file in your editor +# Edit the file: remove <<<<<<, =======, >>>>>> markers +# Keep the content you want + +# 4. After editing, mark the file as resolved +git add src/index.html + +# 5. Complete the merge +git commit +# Git auto-fills the merge commit message + +# Check the result +git log --oneline -3 +``` + +
    + +
    +GitHub CLI (gh) alternative - checking PR conflict status + +Check whether a PR has conflicts without opening a browser: + +```bash +# View PR status (shows merge state) +gh pr view 42 + +# Check all PR checks and merge readiness +gh pr checks 42 + +# View the diff to understand what changed +gh pr diff 42 +``` + +If conflicts exist, the `gh pr view` output shows "This branch has conflicts that must be resolved." Resolve locally using `git merge` (above) then push, or use the web editor. + +
    + + +## Summary Checklist + +```text +Before you start: + □ My PR is small and focused (fewer conflicts = easier life) + □ I checked that others aren't editing the same files + +When you see a conflict: + □ Don't panic - conflicts are normal + □ Read both versions (between <<< and ===, and between === and >>>) + □ Decide: keep one, keep both, or combine intelligently + □ Remove ALL three conflict marker lines (<<<, ===, >>>) + □ Verify the final file makes sense + □ Mark as resolved → Commit merge + +After resolving: + □ Re-check that the PR description and issue link are still accurate + □ Comment on the PR: "Resolved merge conflict - kept both the aria-label and type attribute" + □ Request re-review if reviewers already approved before the conflict was introduced +``` + + +## Try It: Read a Conflict (Without Fear) + +**Time:** 2 minutes | **What you need:** Any text editor or just read below + +Read this merge conflict aloud. The goal is not to resolve it - just to understand what you're hearing: + +```text +The button should have an +<<<<<<< HEAD +aria-label="Submit form" +======= +aria-label="Send your response" +>>>>>>> feature-branch +attribute for screen readers. +``` + +Answer these three questions: + +1. **What does your branch say?** (The text between `<<<<<<< HEAD` and `=======`) +2. **What does the other branch say?** (The text between `=======` and `>>>>>>>`) +3. **Which version would you keep, and why?** + +**You're done.** You just read a merge conflict. That's the entire skill - everything else is just choosing which lines to keep and deleting the three marker lines. + +> **What success feels like:** Conflicts aren't mysterious anymore. They're just two versions side by side with markers telling you which is which. You already know how to pick the right one. + + +> ### Day 2 Amplifier - Copilot Chat & Conflict Prevention +> +> **Resolve at least one conflict completely by hand before using any AI assistance.** You must be able to read `<<<<<<<`, `=======`, and `>>>>>>>` markers and understand what each version represents. An AI-suggested resolution you cannot independently verify is a liability - you are accepting a change you do not understand into a codebase other people depend on. +> +> Once you have mastered manual conflict resolution: +> +> - **In VS Code** - Copilot Chat (`Ctrl+Shift+I`) can explain a conflict in plain language - *"Person A renamed the button to 'Submit Form'; Person B renamed it to 'Send Message'. Which intent should take priority?"* - but you decide what survives +> - **In your repo** - Accessibility Agents' `@pr-review` can identify high-risk overlapping changes before a conflict occurs, flagging when two contributors are editing the same file area and giving you time to coordinate before it escalates +> - **In the cloud** - GitHub Agentic Workflows can detect stale PRs diverging from `main` and automatically notify contributors with a suggested rebase checklist - preventing the conflict before it is ever introduced +> +> *Understanding conflict markers is not a stepping stone to letting AI handle conflicts. It is the skill that tells you when AI got it wrong.* + + +> **Challenge Time:** Check the [Challenge Hub](CHALLENGES.md) for **Challenge 7: Survive a Merge Conflict**. Follow the steps to resolve it, then move to [Chapter 08: Open Source Culture](08-open-source-culture.md). + +--- + + +*Next: [Chapter 08: Open Source Culture](08-open-source-culture.md)* +*Back: [Chapter 06: Working with Pull Requests](06-working-with-pull-requests.md)* +*Related appendices: [Appendix E: Advanced Git](appendix-e-advanced-git.md)* + + + diff --git a/admin/qa-bundle/docs/08-open-source-culture.md b/admin/qa-bundle/docs/08-open-source-culture.md new file mode 100644 index 0000000..92dd974 --- /dev/null +++ b/admin/qa-bundle/docs/08-open-source-culture.md @@ -0,0 +1,1191 @@ +# Culture, Etiquette, and Community Standards +> +> **Listen to Episode 8:** [Open Source Culture and Etiquette](../admin/PODCASTS.md) - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. + +> **Related appendices:** [Appendix M: Accessibility Standards](appendix-m-accessibility-standards.md) | [Appendix F: Git Security](appendix-f-git-security.md) | [Appendix O: Branch Protection](appendix-o-branch-protection.md) | [Appendix W: GitHub Pages](appendix-w-github-pages.md) +> **Authoritative sources:** [GitHub Docs: Contributing to open source](https://docs.github.com/en/get-started/exploring-projects-on-github/contributing-to-a-project) | [Open Source Guides: How to Contribute](https://opensource.guide/how-to-contribute/) + + +## How to Be an Effective and Respectful Open Source Contributor + +> Technical skills get your code into a project. Communication skills keep you welcomed in the community. This guide covers the human side of open source. + + +## Workshop Recommendation (Chapter 8) + +Chapter 8 is a **communication and culture chapter**. + +- **Challenge count:** 1 guided reflection (no bot grading) +- **Automation check:** none - communication quality is too subjective for fair automated scoring +- **Evidence:** structured reflection comment on your assigned challenge issue +- **Pattern:** read, reflect, commit to one behavior + +### Chapter 8 Challenge Set + +1. **Guided reflection** - read the chapter, then post a short reflection comment committing to three specific collaboration behaviors. + +### Challenge 8.1 Step-by-Step: Guided Reflection + +**Goal:** Identify three concrete communication behaviors you will practice during the rest of the workshop. + +**Where you are working:** your assigned Chapter 8 challenge issue in your Learning Room repository on GitHub.com. + +1. Read through the chapter content below, paying attention to the sections on GitHub Flow, constructive feedback, and asking for help. +2. As you read, think about one situation from Day 1 where communication helped (or could have helped) you. +3. Open your **assigned Chapter 8 challenge issue** (the one titled "Chapter 8.1: Guided Reflection (@yourname)"). +4. Scroll to the comment box at the bottom of the issue. +5. Post a reflection comment using this format: + +```text +Chapter 8 reflection: +- One respectful review habit I will use: +- One way I will ask for help clearly: +- One way I will respond to feedback constructively: +``` + +6. For each prompt, write one specific, actionable sentence - not a vague goal. Examples: + - Good: "I will start review comments with what the author did well before suggesting changes." + - Vague: "I will be nice." + - Good: "I will include the exact step where I got stuck and what I already tried." + - Vague: "I will ask good questions." +7. Activate the **Comment** button (or press `Ctrl+Enter`). + +**You are done when:** Your reflection comment appears on the issue with three specific, actionable behaviors. + +### Completing Chapter 8: Submit Your Evidence + +The reflection comment itself is your evidence. No additional steps are needed. The facilitator reviews your comment for specificity. Close your Chapter 8 challenge issue when done. + +### Expected Outcomes + +- Student can name specific, actionable respectful collaboration behaviors. +- Student can prepare a constructive feedback style before review work in later chapters. +- Student feels safer asking for help in public threads. + +### If You Get Stuck + +1. Use one simple sentence per prompt - do not overthink it. +2. Focus on one real behavior you can start doing today, not an abstract principle. +3. If writing feels hard, draft bullet points first in a text editor, then paste into the comment. +4. Look at the "Giving Feedback" and "Asking for Help" sections in this chapter for concrete examples. +5. Ask facilitator for one example response and adapt it to your own words. +6. Finished but not sure you did it right? Compare your work against the [Challenge 8 reference solution](solutions/solution-08-culture.md). + +### Learning Moment + +Technical quality and communication quality work together. Respectful, clear communication helps good code get merged faster. The behaviors you commit to here will directly improve your PR reviews in Chapters 12 and 14. + +### Learning Pattern Used in This Chapter + +1. Read and absorb community norms (not just rules, but reasons). +2. Reflect on personal experience (what worked, what was hard). +3. Commit to specific behaviors in writing (public accountability). +4. Apply those behaviors in upcoming chapters (reviews, comments, PRs). + + +## GitHub Flow - The Standard Contribution Workflow + +Before diving into communication norms, it helps to understand the workflow that gives all of those conversations their context. **GitHub Flow** is the lightweight branching model recommended for open source contribution. It is simple by design and works whether you are making a one-line documentation fix or a major feature addition. + +### The Six Steps of GitHub Flow + +```text +1. Create a branch + └─ Branch off main with a descriptive name + (e.g., fix/missing-alt-text, docs/update-contributing-guide) + +2. Make your changes and commit + └─ Work in small, logical commits with clear messages + Each commit should represent one coherent, complete change + +3. Open a Pull Request + └─ Share your work early - even as a Draft PR + Describe what you changed, why, and how to test it + Link to the related issue (Closes #42) + +4. Discuss and review + └─ Reviewers leave feedback → you refine your work + This is collaborative, not adversarial + +5. Pass status checks + └─ Automated tests and linting must pass + The project's quality gates exist to protect everyone + +6. Merge + └─ A maintainer merges your PR into main + The linked issue closes automatically + Your contribution is now part of the project +``` + +### Why This Model Works + +- **`main` is always deployable.** Nothing goes into `main` directly - every change goes through a PR and review. This protects the project and all its users. +- **Branches are cheap and disposable.** Create a branch per task. Delete it after merging. There is no overhead to starting fresh. +- **PRs are the unit of conversation.** Everything about a change - the why, the tradeoffs, the review, the approval - lives in one place. +- **Small changes move faster.** A 5-file PR gets reviewed in an hour. A 50-file PR sits for days. The most effective contributors keep PRs small and focused. + +### GitHub Flow vs Git Flow + +You may encounter "Git Flow" (sometimes written "GitFlow") in older projects or enterprise environments. This section explains what Git Flow is, how it differs from GitHub Flow, and why this workshop teaches GitHub Flow. + +#### What Git Flow Is + +Git Flow is a branching model published by Vincent Driessen in 2010. It was designed for teams that ship versioned releases on a schedule (desktop software, mobile apps, embedded systems). It defines five branch types: + +The following table describes each Git Flow branch type, its lifetime, and its purpose. + +| Branch | Lifetime | Purpose | +| --- | --- | --- | +| `main` (or `master`) | Permanent | Always reflects the latest production release. Only receives merges from `release/` or `hotfix/` branches. | +| `develop` | Permanent | Integration branch where completed features accumulate. Represents the next planned release. | +| `feature/` | Temporary | Branched from `develop`. One branch per feature. Merged back into `develop` when complete. Deleted after merge. | +| `release/` | Temporary | Branched from `develop` when enough features are ready. Used for final testing, version bumps, and changelog updates. Merged into both `main` and `develop`, then deleted. | +| `hotfix/` | Temporary | Branched from `main` to patch a critical production bug. Merged into both `main` and `develop`, then deleted. | + +#### How the Git Flow Cycle Works + +1. Developers branch `feature/my-feature` off `develop` and work there. +2. Completed features merge back into `develop` via pull request. +3. When `develop` has enough features for a release, a `release/1.2.0` branch is created. +4. The release branch gets final testing, bug fixes, and version number updates. +5. The release branch merges into `main` (tagged with the version) and back into `develop`. +6. If a critical bug is found in production, a `hotfix/` branch is created from `main`, fixed, and merged into both `main` and `develop`. + +#### How GitHub Flow Differs + +The following table compares GitHub Flow and Git Flow across key dimensions. + +| Dimension | GitHub Flow | Git Flow | +| --- | --- | --- | +| Long-lived branches | `main` only | `main` and `develop` (plus temporary `release/` and `hotfix/`) | +| Feature work | Branch off `main`, PR back to `main` | Branch off `develop`, PR back to `develop` | +| Releases | Every merge to `main` is deployable | Explicit `release/` branches with version numbers | +| Hotfixes | Same as any other PR to `main` | Dedicated `hotfix/` branch merged to both `main` and `develop` | +| Complexity | Low - one rule: `main` is always deployable | High - multiple branch types with specific merge targets | +| Best for | Continuous deployment, web apps, open source | Scheduled releases, versioned software, large enterprise teams | + +#### When You Might See Git Flow + +- **Enterprise products** with quarterly or annual release cycles +- **Mobile apps** that go through app store review before release +- **Embedded systems or firmware** where "deploying" means shipping hardware +- **Legacy projects** that adopted it before continuous deployment became common + +#### Why This Workshop Uses GitHub Flow + +For open source contribution - especially at a hackathon or when contributing to web-based projects - **GitHub Flow is what you want**. It is what GitHub itself uses and what most modern open source projects follow. The single-branch simplicity means you can focus on your contribution rather than navigating branch logistics. + +If you join a project that uses Git Flow, the pull request skills you learn here transfer directly. The difference is which branch you target (usually `develop` instead of `main`) and the additional coordination around release timing. + +### The Unwritten Rule: One Thing Per Branch + +A branch and its PR should do **one thing**. If you are fixing a broken link and you notice a typo nearby, fix the typo in a **separate branch and PR**. This keeps reviews fast, history clean, and reduces the risk of one unrelated problem blocking an urgent fix. + +### Learning Cards: GitHub Flow + +
    +Screen reader users + +- The six steps (branch, commit, PR, review, checks, merge) map to six distinct pages on GitHub; you can verify your stage by pressing `1` to hear the page title on each +- When you open a PR, press `D` to the "Pull request navigation tabs" landmark; the Conversation tab confirms your PR is open and shows the linked issue +- After merge, press `G I` to jump to the Issues tab and verify the linked issue closed automatically (it now shows a purple "Closed" badge) + +
    + +
    +Low vision users + +- Each PR in the Pull Requests list has a colored icon: green circle for open, purple merged icon for merged, red circle for closed +- The "Compare & pull request" yellow banner appears at the top of the repo after pushing a branch; it is full-width and prominent at any zoom level +- Before merging, the status checks area below the PR description shows green checkmarks (passed) or red X marks (failed); zoom in to read individual check names + +
    + +
    +Sighted users + +- GitHub Flow uses one long-lived branch (`main`) plus short-lived feature branches; the branch dropdown on the Code tab shows all active branches +- After pushing, look for the yellow "Compare & pull request" banner at the top of the repository page to quickly open a PR +- The PR timeline on the Conversation tab shows the entire story: description, bot checks, review comments, and merge status in chronological order + +
    + + +## Keeping Your Fork Up to Date + +When you fork a repository, you get a snapshot of the project at that moment. The original repository (called "upstream") continues to evolve. To keep your fork current with upstream changes: + +### Why Sync Your Fork? + +- **Stay compatible** - upstream changes may affect your work +- **Avoid conflicts** - the longer you wait, the more conflicts you'll face when merging +- **Get bug fixes** - benefit from improvements made while you worked +- **Keep branches clean** - start new PRs from an up-to-date main branch + +### Method 1: GitHub Web Interface (Easiest) + +
    +Visual / mouse users + +1. Navigate to your fork's main page: `github.com/your-username/repo-name` +2. Look for the sync indicator: "This branch is X commits behind upstream/main" +3. Click the **"Sync fork"** button +4. Click **"Update branch"** + +GitHub merges the upstream changes into your fork automatically. + +
    + +
    +Screen reader users (NVDA / JAWS / VoiceOver) + +1. Navigate to your fork's main page: `github.com/your-username/repo-name` +2. The sync button appears in the landmark that contains the branch selector +3. Press `D` to cycle through landmarks until you reach that region +4. Press `B` to cycle buttons until you hear "Sync fork" → press `Enter` +5. A dialog or page update presents "Update branch" - activate it + +
    + +### Method 2: Git Command Line (VS Code Terminal) + +If you're working locally in VS Code: + +#### One-time setup - add the upstream remote + +```bash +git remote add upstream https://github.com/original-owner/repo-name.git +git remote -v # Verify it was added +``` + +#### Sync process + +```bash +# 1. Switch to your main branch +git checkout main + +# 2. Fetch upstream changes +git fetch upstream + +# 3. Merge upstream's main into yours +git merge upstream/main + +# 4. Push the updated main to your fork on GitHub +git push origin main +``` + +## When to sync + +- Before starting work on a new feature +- Before submitting a PR (to ensure you're working off the latest code) +- Periodically on long-running branches (weekly if actively developed) + +### Method 3: GitHub Desktop + +1. Open GitHub Desktop +2. Select **Repository → Pull** to get your fork's latest +3. Select **Branch → Merge into Current Branch** +4. Choose **upstream/main** +5. Push the changes to your fork on GitHub + +### Learning Cards: Keeping Your Fork Up to Date + +**Screen reader users:** +- In the GitHub web interface, press `D` to cycle landmarks until you reach the branch region, then press `B` to find the "Sync fork" button. +- In the terminal, run `git remote -v` to confirm your upstream remote is configured before fetching -- the output reads back both `origin` and `upstream` URLs. +- After `git fetch upstream && git merge upstream/main`, run `git log --oneline -3` to hear the latest commits and verify the merge succeeded. + +**Low-vision users:** +- On github.com, the "Sync fork" button and its "X commits behind" indicator sit near the branch selector -- zoom to 200% and the button remains in the same row. +- In GitHub Desktop, the merge dialog uses high-contrast text for branch names; confirm you see "upstream/main" before activating Merge. +- If the terminal output of `git fetch` scrolls too fast, pipe it through `| more` or increase your terminal font size before running sync commands. + +**Sighted users:** +- The yellow "This branch is N commits behind" banner on your fork's main page is your visual cue -- click **Sync fork** then **Update branch** and watch the banner disappear. +- In GitHub Desktop, the branch graph in History view shows where upstream diverged; after merging, the graph lines should rejoin. +- In VS Code's Source Control sidebar, the sync icon (circular arrows) in the status bar updates your branch with one click once the upstream remote is configured. + +## Writing Good Commit Messages + +Every commit you make includes a message describing what changed. Good commit messages make project history understandable months or years later. They also show professionalism and consideration for future contributors (including yourself). + +### The commit message format + +```text +: + + + + +``` + +### The First Line (Required) + +**Keep it under 50 characters.** This is the commit summary that appears in logs and GitHub's commit list. Think of it as an email subject line. + +**Use the imperative mood:** Write as if giving a command to the codebase. + +"Fix broken link in README" +"Add alt text to hero image" +"Remove deprecated function" + +"Fixed broken link" - past tense +"Fixing broken link" - gerund +"I fixed the broken link" - too personal + +**Why imperative?** It matches Git's autogen messages: "Merge pull request #42" or "Revert commit abc123." + +**Optional prefixes** (common in some projects): + +- `fix:` - bug fix +- `feat:` - new feature +- `docs:` - documentation only +- `style:` - formatting, no code change +- `refactor:` - code restructuring +- `test:` - adding or updating tests +- `chore:` - maintenance (bump dependencies, etc.) + +Example: `fix: correct ARIA label on submit button` + +### The Body (Optional) + +If the summary isn't enough, add a body explaining: + +- **Why** you made the change (more important than what) +- **What** trade-offs you considered +- **How** the change affects behavior + +Leave a blank line between the summary and the body. + +Example: + +```text +feat: add keyboard shortcuts for issue navigation + +The previous interface required excessive tabbing to reach issue actions. +This change adds G+I to jump to issues list and C to comment inline. + +Shortcuts follow GitHub's existing pattern (G+letter for navigation). +Tested with NVDA, JAWS, and VoiceOver. +``` + +### The Footer (Optional) + +Link commits to issues or PRs: + +```text +Closes #42 +Fixes #17 +Part of #89 +``` + +When the commit is merged, GitHub automatically closes linked issues. + +### Atomic Commits + +Each commit should represent **one logical change**. Don't bundle unrelated fixes into a single commit. + +Good: One commit adds alt text; another fixes a typo +Bad: One commit adds alt text, fixes a typo, reformats code, and updates dependencies + +**Why?** If a commit introduces a bug, you want to revert just that change-not everything. + +### Common mistakes to avoid + +- "WIP" or "more changes" - not descriptive +- "Update file.js" - GitHub already knows that +- "Fixed it" - doesn't say what "it" is +- Commit messages filled with expletives or frustration +- Extremely long summaries that get cut off in logs + +### Good commit messages in practice + +```text +fix: prevent crash when username contains special characters + +Previously, usernames with @ or # caused a parsing error in the +notification system. This escapes special characters before processing. + +Fixes #142 +``` + +```text +docs: add screen reader instructions to contribution guide + +New section covers NVDA, JAWS, and VoiceOver setup for contributors +using assistive technology. Based on workshop feedback. + +Part of #200 +``` + +**When you make a habit of writing good commit messages, you build trust.** Maintainers see that you care about the project's long-term health, not just your immediate contribution. + +### Learning Cards: Writing Good Commit Messages + +
    +Screen reader users + +- In VS Code's Source Control panel (`Ctrl+Shift+G`), the commit message input is the first field; type your message there and press `Ctrl+Enter` to commit +- On the Commits tab of a PR, press `3` to jump between date-group headings, then `I` to navigate individual commits; each commit announces its message and author +- Good commit messages start with a verb in imperative mood ("Add," "Fix," "Remove"); your screen reader will read these as the first word when navigating commit lists + +
    + +
    +Low vision users + +- In the commit history view, only the first line (subject) of each commit message is visible by default; click "..." to expand the full body +- Keep the subject line under 50 characters so it does not truncate in GitHub's commit list view at any zoom level +- VS Code shows a vertical ruler in the commit message field at 72 characters; lines longer than this may wrap awkwardly in terminal and email displays + +
    + +
    +Sighted users + +- The commit list on GitHub shows one commit per row with the subject line, author avatar, and relative timestamp; descriptive subjects make scanning easy +- Use the format "type: description" (e.g., `fix: remove broken link in setup guide`) to categorize commits at a glance +- Separate the subject from the body with a blank line; GitHub renders the body as expandable detail below the subject + +
    + + +## The Nature of Open Source Communication + +Open source collaboration happens primarily **in writing**, **asynchronously**, **in public**. Understanding these three characteristics shapes everything about how we communicate. + +### In writing + +- There is no tone of voice, body language, or immediate clarification +- A message that sounds terse in your head may read as hostile to the reader +- Sarcasm and irony are nearly impossible to convey safely - avoid them +- **Solution:** Be explicit. "I think this might cause a problem because..." is clearer than "This is problematic." + +### Asynchronously + +- Comments are not instant messages - the reader may see your post hours or days later +- You may be in a rush; they are not receiving urgency from your message +- Comments exist without the context of what you were thinking when you wrote them +- **Solution:** Provide all necessary context in every message. Do not assume continuity. + +### In public + +- Everything you write is visible to everyone, forever, and may be indexed and shared +- Future contributors, employers, and the broader community will read your words +- A dismissive reply to a beginner casts a shadow on the entire project +- **Solution:** Write as if your most supportive and most critical reader are both watching. + + +## The Anatomy of Helpful Feedback + +Whether commenting on an issue, reviewing a PR, or responding to a question, effective feedback has a structure: + +### 1. Acknowledge what's working + +Before identifying problems, name what is good. This is not flattery - it is accuracy. Most contributions have real strengths. + +> "The approach of separating the icon from the button text is exactly right - makes the screen reader label much cleaner." + +### 2. Identify the specific concern + +Be precise. Vague feedback is not actionable. + +"This code is inaccessible." +"This button has no accessible name - `aria-label` or visible text is needed for screen readers to announce its purpose." + +### 3. Explain why it matters + +Context turns a complaint into a lesson. It also respects the contributor - they deserve to understand, not just comply. + +> "Without an accessible name, screen readers will announce the button as simply 'button,' which gives the user no information about what activating it will do." + +### 4. Suggest a path forward (when you can) + +If you have an idea for a solution, offer it as a suggestion, not a mandate. + +> "Something like `aria-label='Close navigation menu'` would work well here. Happy to help if you'd like." + +### 5. Signal the weight of the concern + +Help contributors understand what is a blocker versus a preference. + +- `nit:` - minor, optional suggestion ("nit: there's a trailing space here") +- No qualifier - normal concern, should be addressed +- "This is a blocker because..." - must be fixed before merge +- "Just a thought, not a blocker..." - feedback but no requirement + + +## Language and Tone + +### Prefer "we" or describe the code, not the person + +"You made an error here." +"There's an error here." or "This line does X but we need Y." + +### Use tentative language for uncertainty + +"This will crash on mobile." +"I think this might cause issues on mobile - have you tested with a narrower viewport?" + +### Acknowledge cultural and language diversity + +Open source is global. Contributors may be: + +- Writing in their second or third language +- Unfamiliar with idioms ("it's a no-brainer," "hit the ground running," "over the top") +- Accustomed to different norms of directness + +**When reading someone's comment:** Assume good intent unless there is clear evidence otherwise. +**When writing:** Choose plain words over clever ones. + +### Avoid urgency markers unless genuinely urgent + +"I need this fixed ASAP" +"This is blocking our release scheduled for next Friday - is there capacity to look at it this week?" + + +## Commenting Etiquette + +### Keep comments focused + +Each comment should address one concern. If you have three issues, leave three comments - unless they are closely related. + +### Don't leave comments unresolved + +If you asked a question and got an answer, respond. "Thanks, that makes sense" or resolving the conversation thread signals that the thread is complete. + +### Resolving conversations + +On a PR, conversations (inline comment threads) can be "resolved" once addressed. The author of the change and the reviewer can both resolve them. If you addressed a reviewer's comment, resolve the thread and leave a note: "Fixed in commit a1b2c3d." + +### Do not "pile on" + +If five people already said the same thing about an issue, you don't need to add a sixth comment saying the same thing. A reaction on an existing comment is enough. + +### Reactions + +GitHub reactions () are an efficient way to express agreement, appreciation, or concern without adding noise to a thread. + +### Saved Replies - Your Accessibility Win + +GitHub lets you save frequently used responses as **Saved Replies** - reusable text snippets you can insert into any comment box with a few keystrokes. This is a significant accessibility win for anyone who types the same comments repeatedly during triage, reviews, or issue management. + +#### Common uses + +- "Thank you for your contribution! I'll take a look this week." +- "This looks like a duplicate of #N - closing, please continue the discussion there." +- "I've labeled this `good first issue`. To claim it, leave a comment saying you'd like to work on it and I'll assign you." +- Your team's standard accessibility issue acknowledgement template + +#### Creating a Saved Reply + +1. Navigate to `github.com/settings/replies` +2. Activate **"Add a saved reply"** +3. Give it a title (e.g., "Good first issue claim") - this is what you search for +4. Type the full reply text in the body (Markdown is supported) +5. Save + +#### Using a Saved Reply in a comment + +1. Navigate to any comment text area +2. Activate the **Saved Replies button** (the speech bubble icon in the comment toolbar, or press `Ctrl+.` if enabled) +3. A dropdown appears showing your saved replies - type to filter by title +4. Select the reply - it inserts into the text area +5. Edit as needed before submitting + +#### Screen reader path + +```text +In a comment text area: +→ Tab to the toolbar icons +→ "Saved replies" button → Enter +→ Filter by typing part of the title +→ ↑/↓ to select → Enter to insert +``` + +**Limit:** GitHub allows up to 100 saved replies per account. + +### Learning Cards: Commenting Etiquette + +
    +Screen reader users + +- Press `D` to jump to the "Add a comment" landmark on any issue or PR, then switch to Focus Mode (`NVDA+Space`) to type your comment +- Use `Ctrl+Enter` to submit a comment directly from the text area without needing to find the Submit button +- In a comment, type `@` followed by a username to trigger autocomplete; press `Down Arrow` to navigate suggestions and `Enter` to select + +
    + +
    +Low vision users + +- The comment box has a formatting toolbar above it (bold, italic, code, link); at high zoom these icons may wrap but remain functional +- Use the Preview tab next to Write to check how your Markdown renders before posting; this helps catch formatting issues at any zoom level +- Saved replies are accessed via the speech bubble icon in the comment toolbar; they insert pre-written text to save typing on common responses + +
    + +
    +Sighted users + +- The comment box appears at the bottom of every issue and PR Conversation tab; it supports full Markdown with a live Preview tab +- Use `Ctrl+B` for bold, `Ctrl+I` for italic, `Ctrl+K` for links, and `Ctrl+E` for inline code while typing in the comment area +- GitHub renders @mentions, issue references (`#42`), and emoji shortcodes (`:+1:`) automatically in the posted comment + +
    + + +## Code Review Etiquette - For Reviewers + +### Review the code, not the person + +"You clearly don't understand accessibility." +"This implementation doesn't account for keyboard navigation - here's how to add it." + +### Don't gatekeep knowledge + +If a contributor makes a mistake because they didn't know something, explain the concept. They're here to learn. + +### Ask questions instead of making demands + +"Change this to use `aria-label`." +"What do you think about using `aria-label` here instead? Screen readers would then announce the button's purpose directly." + +### Distinguish opinion from requirement + +If something is your stylistic preference but NOT a bug or correctness issue, say so. + +> "The current implementation is correct. I personally prefer the pattern in utils/helpers.js, but this is a nit - feel free to keep it as-is." + +### Approve explicitly + +When a PR is ready to merge, say so clearly - either by using the Approve review option, or in a comment: "This looks great to me! No blockers on my end." + + +## Code Review Etiquette - For Authors + +### Say thank you + +When someone takes time to review your work, acknowledge it - even if you disagree with some feedback. + +> "Thanks so much for the thorough review! I've addressed all but the last comment - see my note there." + +### Don't take feedback personally + +Code review is about the code, not your worth as a person or developer. Even the most senior contributors receive change requests. + +### Explain your choices + +If you are keeping your implementation despite feedback, explain why. + +> "I considered `aria-label` here, but I went with a visually-hidden `` instead because it allows translators to localize the text more easily. Let me know if you think that tradeoff is wrong." + +### Surface blockers early + +Don't wait until you have finished a 500-line PR to mention that you weren't sure about the approach. Open a Draft PR early and ask. + + +## Inclusive Commenting for Accessibility Issues + +When filing or discussing accessibility bugs, additional context helps: + +- **Describe what was announced** - quote your screen reader's exact output when possible +- **Do not assume all users experience the same thing** - NVDA users, JAWS users, and VoiceOver users may have different experiences +- **Be precise about versions** - accessibility behavior changes between OS and screen reader versions +- **Represent the gap** - "This means that [group of people] cannot [do the thing]" - frame in impact, not just symptoms +- **Don't catastrophize or be dismissive** - "No blind person can use this" may be inaccurate; be precise about the specific failure and its scope + + +## The "Good First Issue" Social Contract + +When a maintainer labels an issue `good first issue`, they are: + +- **Investing time** - good first issues require extra documentation and mentorship +- **Signaling welcome** - they want to support a new contributor + +When you take a good first issue, your responsibilities: + +1. **Comment to claim it** - "Hi, I'd like to work on this. Can I be assigned?" +2. **Wait for assignment** - do not start until assigned; two people working in parallel wastes everyone's time +3. **Check in if stuck** - "I've been working on this for a day and I'm stuck on X - can you point me in the right direction?" +4. **Check in if unavailable** - "Life got busy and I can't finish this by the original estimate - is it okay if I extend by a week, or should you reassign?" +5. **Don't disappear** - if you claim an issue, see it through or explicitly hand it back + + +## Handling Difficult Situations + +### When you receive harsh feedback + +1. Take a breath before responding - there is no urgency; the thread will wait +2. Look for the valid concern underneath the harsh words +3. Respond to the concern, not the tone +4. If the behavior crosses into harassment, report it via the "..." button on the comment → "Report" + +### When you disagree with a decision + +1. Make your case once, clearly and with evidence +2. Accept that the maintainer has the final say in their project +3. If you strongly disagree, you can fork the project and take it in a different direction - this is legitimate in open source + +### When someone is rude to you + +1. You do not have to engage +2. You can reply once to state your boundary: "I'm happy to discuss the technical merits, but I'd prefer if we kept the conversation constructive." +3. Report via GitHub's reporting tools if the behavior is abusive + +### When you accidentally caused offense + +1. Acknowledge it directly: "I can see how that came across as dismissive - that wasn't my intention." +2. Do not over-explain or defend excessively +3. Adjust going forward + + +## Writing Your First README + +> **See also:** [Appendix W: GitHub Pages](appendix-w-github-pages.md) for publishing your README as a website. + +A README is the front door of your project. It is the first file visitors read, and often the only file they read before deciding whether to stay or move on. + +### What belongs in a README + +Every README should answer these questions, roughly in this order: + +| Section | What it answers | +| --- | --- | +| **Project name** | What is this? | +| **Description** | Why does it exist? What problem does it solve? | +| **Installation** | How do I get it running on my machine? | +| **Usage** | How do I use it once it is installed? | +| **Contributing** | How can I help? (or link to CONTRIBUTING.md) | +| **License** | What am I allowed to do with this code? | + +You do not need all six sections for a tiny project, but you should have at least a name, a one-sentence description, and a license. + +### A skeleton you can copy + +```markdown +# Project Name + +One sentence that describes what this project does. + +## Installation + +Steps to install and set up the project locally. + +## Usage + +Show a basic example of how to use the project. + +## Contributing + +Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for details. + +## License + +This project is licensed under the MIT License. See [LICENSE](LICENSE) for the full text. +``` + +### Accessibility in READMEs + +Your README is a web page -- GitHub renders it as HTML. That means the same accessibility rules apply: + +- **Alt text for images and badges.** A badge that says `![](https://img.shields.io/badge/build-passing-green)` is invisible to screen readers. Write `![Build status: passing](...)` instead. +- **Heading hierarchy.** Use `#` for the project name, `##` for top-level sections, `###` for subsections. Never skip levels. +- **Descriptive link text.** Write `See the [installation guide](docs/install.md)` -- not `Click [here](docs/install.md)`. + +> **Screen reader tip:** When you navigate a README with a screen reader, the heading list (`Insert + F7` in NVDA, `Rotor > Headings` in VoiceOver) is your table of contents. A flat list of `##` headings with clear names makes the document fast to scan. + +### Good README vs. bad README + +**Bad:** A single paragraph that says "This is my project. Run it with npm start." No headings, no license, no description of what the project does. + +**Good:** A clear name, a sentence explaining the purpose, a short install block, a usage example, a link to CONTRIBUTING.md, and a license section -- all under well-structured headings. + +The difference is about two minutes of writing and saves every future visitor from guessing. + +### Learning Cards: Writing Your First README + +**Screen reader users:** +- Maintain strict heading hierarchy (`#` then `##` then `###`) -- your heading list shortcut (`Insert+F7` in NVDA, Rotor in VoiceOver) becomes a usable table of contents only when levels are not skipped. +- Write descriptive alt text on every badge and image: `![Build status: passing](...)` rather than an empty `![]()` that reads as "image" with no context. +- Use real Markdown link text (`[installation guide](docs/install.md)`) instead of bare URLs, so your screen reader announces the destination rather than spelling out a long URL. + +**Low-vision users:** +- Use `##` headings to create clear visual blocks -- GitHub's rendered Markdown adds spacing and larger font weight to headings, making the README scannable at high zoom. +- Keep code blocks short (under 10 lines) and use syntax-highlighted fenced blocks (` ```bash `) so keywords stand out in your high-contrast or dark theme. +- Put the most important information (project name, one-line description, install command) in the first 5 lines so it is visible without scrolling at 200% zoom. + +**Sighted users:** +- Preview your README in VS Code (`Ctrl+Shift+V`) or on GitHub after pushing -- the rendered view reveals formatting mistakes that are invisible in raw Markdown. +- Add a badge row near the top (build status, license, version) for a quick visual health check, but always include alt text for each badge. +- Use a table for structured information (like the "What belongs in a README" table in this section) -- tables render as clean grids on GitHub and are faster to scan than bullet lists for tabular data. + +## Community Health Files + +Community health files tell contributors how your project operates before they write a single line of code. GitHub recognizes these files and surfaces them in the repository's **Community Standards** page (under the **Insights** tab), so visitors can see at a glance which expectations are documented. + +### CONTRIBUTING.md + +This file answers the question every newcomer asks: "How do I help?" A good CONTRIBUTING.md covers: + +- **How to report bugs** -- what information to include, which issue template to use +- **How to suggest features** -- whether to open a Discussion first or go straight to an Issue +- **Code style** -- formatting rules, linter settings, naming conventions +- **PR process** -- branch naming, commit message format, who reviews, how long to wait + +Keep the tone welcoming. A sentence like "We are glad you are here" costs nothing and signals that newcomers are expected, not tolerated. + +**Always read CONTRIBUTING.md before opening a PR.** Skipping it leads to rejected PRs and wasted effort on both sides. See [Chapter 6](06-working-with-pull-requests.md) for the full PR workflow. + +### CODE_OF_CONDUCT.md + +A code of conduct sets the social contract for your project. Without one, "acceptable behavior" is whatever each participant assumes it is -- and those assumptions vary widely. + +Most projects adopt the [Contributor Covenant](https://www.contributor-covenant.org/), which covers: + +- Expected behavior (be respectful, use welcoming language, accept constructive criticism) +- Unacceptable behavior (harassment, trolling, personal attacks) +- Enforcement -- who to contact and what happens after a report + +When you see a CODE_OF_CONDUCT.md in a repository, it means the maintainers take community health seriously, there is a process for reporting violations, and you are both protected and expected to protect others. + +### SECURITY.md + +> **See also:** [Appendix F: Git Security](appendix-f-git-security.md) and [Appendix P: Security Features](appendix-p-security-features.md) for security best practices. + +If someone discovers a vulnerability in your project, you do not want them to file a public issue. A SECURITY.md file tells reporters how to disclose responsibly: + +- **Supported versions** -- which releases still receive security patches +- **How to report** -- a private email address or GitHub's private vulnerability reporting feature +- **What to expect** -- typical response time and disclosure timeline + +Even small projects benefit from this file. It takes five minutes to write and prevents an accidental public disclosure that could affect your users. + +### LICENSE + +Without a license file, your code is "all rights reserved" by default -- meaning nobody can legally use, copy, or modify it, regardless of whether the repository is public. Adding a LICENSE file is a one-time step that makes your project genuinely open source. + +You do not need to become a licensing expert. The [choosealicense.com](https://choosealicense.com/) site walks you through the most common options. For class projects, MIT or Apache 2.0 are typical choices. + +### Finding these files on GitHub + +Navigate to any repository and click **Insights** then **Community Standards**. GitHub shows a checklist of which community health files are present and links to add any that are missing. This is the fastest way to audit a project before you contribute. + +> **Screen reader tip:** The Community Standards page is a simple checklist. Each item is a link -- if the file exists, the link text includes a checkmark. You can tab through the list to quickly confirm which files are in place. + +### Learning Cards: Community Health Files + +
    +Screen reader users + +- Navigate to any repo's Insights tab by pressing `D` to the repository navigation landmark, then `K` to find "Insights"; from there, find "Community Standards" +- On the Community Standards page, each file is announced as a list item with a checkmark status (present or missing); `Tab` through the list to audit quickly +- When creating a README, use heading levels (`#`, `##`, `###`) so screen readers can navigate sections with `H`; start with a single H1 for the project name + +
    + +
    +Low vision users + +- The Community Standards checklist uses green checkmarks for present files and grey circles for missing ones; in high-contrast mode these use distinct system colors +- README files render below the file table on the repository's Code tab; zoom in on the rendered Markdown for the most comfortable reading experience +- When writing a README, keep paragraphs short (3-4 sentences) and use bullet lists so the content is scannable at high magnification + +
    + +
    +Sighted users + +- Navigate to Insights tab, then Community Standards to see a checklist of recommended files (README, LICENSE, CONTRIBUTING, CODE_OF_CONDUCT, etc.) +- Each missing file has an "Add" link next to it that opens a pre-filled template editor on GitHub +- The README renders as formatted Markdown below the file table on the main Code tab; it is the first thing visitors see when they land on your repository + +
    + + +## When to Use Different Communication Channels + +| Channel | Use For | +| --------- | --------- | +| **Issue** | Bug reports, feature requests, questions about a specific problem | +| **PR comment** | Feedback on a specific code change | +| **PR review** | Formal verdict (approve/request changes) with consolidated feedback | +| **Discussion** | Open-ended conversation, proposals, community Q&A | +| **Email / direct** | Sensitive matters (security vulnerabilities, Code of Conduct reports) | + +**GitHub Discussions are separate from Issues.** Use Discussions for: "What do people think about X approach?" and Issues for: "The X button is broken." + + +## Quick Reference: Phrases That Work + +| Instead of... | Try... | +| --------------- | -------- | +| "This is wrong." | "This looks like it might cause X - is that intended?" | +| "Everyone knows you should..." | "A common pattern for this is..." | +| "This is terrible." | "I think this approach has some drawbacks - here's what I'm seeing." | +| "Fix this." | "What do you think about changing this to X?" | +| "Obviously..." | *(just omit the word "obviously")* | +| "This is a major issue." | "This is a blocker for users who rely on keyboard navigation." | +| "Can't you just..." | "One approach that might work is..." | +| "No." | "I don't think this approach is right for this project because..." | + + +## Try It: Rewrite One Comment + +**Time:** 2 minutes | **What you need:** Just your brain + +Read this code review comment and rewrite it to be constructive: + +> **Original:** "This alt text is bad. Fix it." + +Use the five-step feedback anatomy from this chapter: + +1. **What** you noticed +2. **Why** it matters +3. **What** you suggest +4. **Why** the suggestion helps +5. **Encouragement** + +Here's one way: + +> **Rewritten:** "The alt text on this image says 'image1.png' - screen reader users will hear the filename instead of what's in the image. Could you describe what the screenshot shows, like 'Settings page with the Accessibility section expanded'? That way everyone gets the same information. Nice catch adding the image though - it really helps illustrate the step!" + +Notice: same feedback, completely different experience for the person receiving it. + +> **What success feels like:** You turned a two-word dismissal into help that someone would actually want to receive. That's the difference between a comment that fixes code and a comment that also keeps a contributor coming back. + + +> ### Day 2 Amplifier - Accessibility Agents Outputs Are Your Responsibility +> +> **Every communication principle in this guide applies with extra force when agents are involved.** When `@pr-review` generates review comments, *you* are responsible for their tone before you post them. When `@issue-tracker` drafts a triage reply, *your* name appears on it in the repository's public history. The agent writes - the contributor publishes. +> +> As you work with agents on Day 2, use this guide as your editing checklist: +> +> - **In VS Code** - Review every agent-generated comment against the "anatomy of helpful feedback" section before posting; use the "phrases that work" table to refine anything that reads as automated, generic, or cold +> - **In your repo** - Accessibility Agents outputs are first drafts, not final words; the community you contribute to experiences your judgment, not the agent's draft +> - **In the cloud** - GitHub Agentic Workflow comments must be designed with the same care as human comments: clear purpose, respectful language, and a transparent signal that automation posted them +> +> *A community's culture is shaped by every message posted in its name - including the ones an agent wrote for you.* + + +*Next: [Labels, Milestones, and Projects](09-labels-milestones-projects.md)* +*Back: [Merge Conflicts](07-merge-conflicts.md)* +*Related: [Working with Issues](05-working-with-issues.md) | [Working with Pull Requests](06-working-with-pull-requests.md)* + +--- + +## Contributing to Open Source + +> *This section was previously Appendix T. It is now part of the teaching narrative.* + +> +> **Listen to Episode 37:** [Contributing to Open Source](../admin/PODCASTS.md) - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. + +## A Guide for First-Time Contributors + +> You do not need to be a professional developer to contribute to open source. Documentation, accessibility improvements, and bug reports are among the most valuable contributions any project can receive. + + +## Table of Contents + +1. [What Is Open Source?](#1-what-is-open-source) +2. [Who Can Contribute?](#2-who-can-contribute) +3. [What Makes a Good First Contribution?](#3-what-makes-a-good-first-contribution) +4. [Finding Something to Work On](#4-finding-something-to-work-on) +5. [Reading an Issue Before You Start](#5-reading-an-issue-before-you-start) +6. [Making Your Contribution](#6-making-your-contribution) +7. [Getting Help](#7-getting-help) +8. [After Your Contribution Is Merged](#8-after-your-contribution-is-merged) +9. [Building a Contribution Habit](#9-building-a-contribution-habit) + + +## 1. What Is Open Source? + +Open source software is software whose source code is publicly available. Anyone can read it, use it, and - in most cases - contribute to it. Contributions can include: + +- Fixing bugs in the software +- Writing or improving documentation +- Filing bug reports that help maintainers understand problems +- Reviewing other people's changes and leaving thoughtful feedback +- Translating content into other languages +- Improving accessibility - adding alt text, fixing heading structure, testing with screen readers + +The projects that power much of today's web infrastructure - operating systems, programming languages, screen readers, and developer tools - are maintained by contributors who started exactly where you are now. + + +## 2. Who Can Contribute? + +Contributors come from all backgrounds, skill levels, and countries. A first contribution could be fixing a typo, adding a missing full stop, or filing a bug report that saves a maintainer hours of debugging. + +Assistive technology users bring a perspective that most sighted, mouse-first developers cannot - you notice when heading structure is broken, when a button has no accessible name, or when a form cannot be completed with a keyboard. These are real, high-value contributions that improve projects for everyone. + +You do not need permission to start. If a repository's issues are public, you can file a bug or suggest an improvement today. + + +## 3. What Makes a Good First Contribution? + +A good first contribution is: + +- **Specific** - it addresses one problem clearly, not a general "this could be better" +- **Scoped** - it does not try to fix everything at once; one PR, one problem +- **Described** - the PR or issue explains what changed and why, not just what +- **Tested** - for documentation, this means reading it aloud with your screen reader before submitting; for code, it means verifying the fix works + +### Signs a contribution is too large for a first attempt + +- The PR touches more than three or four files +- You need to understand the entire codebase to make the change +- The issue has been open for a long time with many comments suggesting it is complex + +Start small. A well-executed small contribution is far more valuable than a large contribution that cannot be merged because it is out of scope. + + +## 4. Finding Something to Work On + +Most open source projects label issues that are suitable for new contributors. Look for: + +| Label | Meaning | +| ------- | --------- | +| `good first issue` | Explicitly recommended for first-time contributors | +| `first-timers-only` | Reserved for people making their first contribution to this project | +| `help wanted` | Maintainers are actively looking for someone to pick this up | +| `beginner` or `easy` | Lower complexity than average | +| `documentation` | No coding required - writing or editing docs | +| `accessibility` | Directly relevant to AT users; high-value work | + +**How to search:** On any GitHub repository, go to Issues → filter by label. Or use GitHub's global search: `label:"good first issue" is:open language:markdown` to find documentation issues across all public repositories. + +### Learning Cards: Finding Something to Work On + +**Screen reader users:** +- On a repository's Issues page, use the landmark shortcut (`D` in NVDA browse mode) to jump to the filter region, then type a label name like `good first issue` in the Label filter field and press `Enter` to narrow results. +- GitHub's global search (`label:"good first issue" is:open language:markdown`) returns a results list navigable by heading level -- each issue title is a link, so press `K` (next link) or `Tab` to step through them efficiently. +- Before claiming an issue, press `End` to jump to the bottom of the issue page and listen for recent comments -- if someone already said "I'll take this," move on to the next one. + +**Low-vision users:** +- GitHub color-codes labels, but do not rely on color alone -- hover over a label to see its text name in a tooltip, or use the Label dropdown which lists label names as text. +- Zoom to 150-200% when scanning the Issues list; the issue title, label pills, and comment count remain in a single row up to about 250% zoom before wrapping. +- Use the Sort dropdown ("Newest," "Recently updated") to push stale issues down the list so you focus on actively maintained work first. + +**Sighted users:** +- Skim the colored label pills on the Issues list for `good first issue` (typically green) or `help wanted` (typically yellow) -- these stand out visually in a long list. +- Check the comment count and last-updated date on the right side of each issue row; a high comment count on a `first-timers-only` issue often means someone is already working on it. +- Use GitHub's global search bar with `label:"good first issue" is:open` and add `language:` or `topic:` filters to match your interests across all public repositories. + +## 5. Reading an Issue Before You Start + +Before commenting "I'll take this" on an issue, ask yourself: + +- **Is the description clear enough to act on?** If you are not sure what the problem is, ask a clarifying question before starting work. +- **Is anyone else already working on it?** Look for recent comments from others saying they are working on it, or an open PR that references this issue. If a PR exists, it may already be in review. +- **Is the issue in scope for me?** A documentation task does not require programming knowledge. A bug fix in compiled code may require understanding the codebase. +- **How old is the issue?** Very old issues (2+ years) may be stale or no longer relevant. You can ask the maintainer if it is still valid before investing time. + +If the issue looks right for you, comment briefly to let the team know you are working on it: "I'd like to work on this. I'll open a draft PR shortly." This prevents duplicate work. + + +## 6. Making Your Contribution + +### Tool Cards: Fork, Clone, and Contribute + +**github.com (browser):** +1. Click **Fork** on the repository page, then **Create fork**. +2. Edit files directly in your fork's web interface. +3. Click **Contribute > Open pull request** to submit back to the original. + +**github.dev (web editor):** +1. Fork the repo on github.com first. +2. Navigate to your fork and press `.` to open in the web editor. +3. Edit, commit, and create a PR from the Source Control panel. + +**VS Code Desktop:** +1. Fork on github.com, then clone your fork: `Ctrl+Shift+P` > **Git: Clone**. +2. Create a branch, make edits, commit and push. +3. Use **GitHub Pull Requests: Create Pull Request** to submit. + +**GitHub Desktop:** +1. **File > Clone Repository**, select your fork. +2. Create a branch via **Branch > New Branch**, make edits. +3. Push and click **Create Pull Request** (opens browser). + +**Git CLI / GitHub CLI:** +```bash +gh repo fork owner/repo --clone +cd repo +git checkout -b fix/my-change +# edit files +git add . && git commit -m "fix: description" +git push -u origin fix/my-change +gh pr create +``` + +### The Basic Workflow + +1. **Fork the repository** - creates your own copy on GitHub +2. **Clone your fork** to your computer (or open a Codespace - see [Appendix N](appendix-j-cloud-editors.md)) +3. **Create a branch** - name it something descriptive: `fix/broken-link-setup-guide` +4. **Make your change** - edit the file, save, verify +5. **Commit with a clear message** - "Fix broken link in setup-guide.md line 34" +6. **Push to your fork** +7. **Open a pull request** from your branch to the original repository's default branch +8. **Respond to review feedback** - maintainers may ask for changes; this is normal and not a rejection + +### Writing a Good PR Description + +A PR description should answer: + +- **What** did you change? +- **Why** was the change needed? +- **How** did you verify it works? + +Example: +> Fixed a broken link on line 34 of `setup-guide.md`. The link pointed to `/docs/old-setup` which no longer exists. Updated it to `/docs/00-pre-workshop-setup.md`, verified the target file exists and the anchor is correct. + +This gives the reviewer everything they need to approve quickly. + + +## 7. Getting Help + +It is always acceptable to ask a question on an issue or pull request. Good questions: + +- **Are specific:** "I'm trying to fix the broken link on line 24 of `setup-guide.md`. The link currently points to `/docs/old-setup`. Where should it point?" +- **Show what you tried:** "I searched the repository for the correct URL but couldn't find a file at that path." +- **Are polite:** Assume good intent from maintainers, even if they are slow to respond. Maintainers are often volunteers with day jobs. + +If you opened a PR and are waiting for a review, it is appropriate to leave one polite follow-up comment after a week or two. Start with: "Hi, just checking in on this PR when you have a moment." + + +## 8. After Your Contribution Is Merged + +When your pull request is merged: + +- Your name appears in the project's **commit history permanently** - it cannot be removed +- The issue you fixed is closed +- You are officially listed as a **contributor** to this project, visible on the repository's Contributors page + +This matters for your GitHub profile. Each merged contribution demonstrates real-world collaboration with a project team: you scoped a problem, communicated with maintainers, addressed feedback, and saw the work through. That record is visible to anyone who views your profile. + +Over time, a series of contributions builds a portfolio that shows how you work - not just what you can do in isolation. + + +## 9. Building a Contribution Habit + +The hardest part of open source contribution is starting. Once you have one merged PR, the next is easier - you know the workflow, you have proof it is possible, and you have already navigated the social dynamics of working with a maintainer. + +### Practical habits + +- **Keep a list** of projects you use and like. These are natural candidates for contributions because you already understand what they do. +- **File bug reports** when you encounter problems, even if you cannot fix them yourself. A clear, reproducible bug report is a real contribution. +- **Review other PRs.** Even as a new contributor, you can leave useful feedback: "Does this change affect screen reader users?" or "The example in the PR description is missing a step." +- **Set a low bar.** A contribution does not need to be impressive. A fixed typo merged into a project used by thousands of people is more valuable than a perfect contribution never submitted. + + +> **Challenge Time:** Complete **Challenge 8: The Culture Layer** in the [Challenge Hub](CHALLENGES.md), then advance to [Chapter 09: Labels, Milestones and Projects](09-labels-milestones-projects.md). + +--- + + +*Next: [Chapter 09: Labels, Milestones, and Projects](09-labels-milestones-projects.md)* +*Back: [Chapter 07: Merge Conflicts](07-merge-conflicts.md)* +*Related appendices: [Appendix M: Accessibility Standards](appendix-m-accessibility-standards.md) | [Appendix F: Git Security](appendix-f-git-security.md) | [Appendix O: Branch Protection](appendix-o-branch-protection.md)* + diff --git a/admin/qa-bundle/docs/09-labels-milestones-projects.md b/admin/qa-bundle/docs/09-labels-milestones-projects.md new file mode 100644 index 0000000..cd6a207 --- /dev/null +++ b/admin/qa-bundle/docs/09-labels-milestones-projects.md @@ -0,0 +1,707 @@ +# Labels, Milestones, and Projects +> +> **Listen to Episode 9:** [Labels, Milestones, and Projects](../admin/PODCASTS.md) - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. + +> **Related appendices:** [Appendix R: Projects Deep Dive](appendix-r-projects-deep-dive.md) | [Appendix A: Glossary](appendix-a-glossary.md) +> **Authoritative sources:** [GitHub Docs: About labels](https://docs.github.com/en/issues/using-labels-and-milestones-to-track-work/managing-labels) | [GitHub Docs: About milestones](https://docs.github.com/en/issues/using-labels-and-milestones-to-track-work/about-milestones) | [GitHub Docs: About Projects](https://docs.github.com/en/issues/planning-and-tracking-with-projects/learning-about-projects/about-projects) + + +## Organizing Work and Cross-Referencing on GitHub + +> Labels, milestones, and projects are the organizational layer of GitHub. They turn a chaotic list of issues into a structured, navigable, prioritized body of work. + + +## Workshop Recommendation (Chapter 9) + +Chapter 9 is a **guided triage chapter** focused on organization skills. + +- **Challenge count:** 1 guided challenge +- **Automation check:** none by default +- **Evidence:** structured issue comment in assigned challenge issue +- **Pattern:** inspect, classify, explain + +### Chapter 9 Challenge Set + +1. **Post a triage recommendation** - read an issue, recommend labels/milestone/project placement, and explain your reasoning. + +### Challenge 9.1 Step-by-Step: Triage Recommendation Comment + +**Goal:** Read the details of a Learning Room issue and post a structured triage recommendation that a maintainer could act on immediately. + +> **Agentic strategy:** Labels and issue states are how we wake up agents. In the Day 2 capstone, you can design an agent that only activates when an issue gets a specific label, such as `needs-review` or `accessibility-check`. + +**Where you are working:** your assigned Chapter 9 challenge issue in your Learning Room repository on GitHub.com, plus one other open issue you will triage. + +1. Open the **Issues** tab in your Learning Room repository. +2. Find any **open issue** that does not already have labels applied (or pick one your facilitator assigns). +3. Read the issue title and full description carefully. Note: + - What type of work is it? (documentation fix, bug report, accessibility improvement, new content) + - How urgent does it seem? (blocking other work, nice-to-have, unclear) + - Which file or area of the repo does it affect? +4. Open your **assigned Chapter 9 challenge issue** (the one titled "Chapter 9.1: Triage Recommendation (@yourname)"). +5. Scroll to the comment box and post a triage recommendation using this format: + +```text +Chapter 9 triage recommendation for issue #[number]: +- Suggested labels: [pick 1-3 from: documentation, bug, accessibility, enhancement, good first issue] +- Suggested milestone: [pick one or write "none - reason"] +- Suggested project board column: [To Do, In Progress, or Needs Triage] +- One-sentence reason: [why you chose these categories] +``` + +6. If you have write access to the repository, apply the recommended labels and milestone directly on the issue you triaged. +7. Activate the **Comment** button. + +**Screen reader tip:** When browsing available labels, open the Labels page (`/labels` path on the repo) to see all label names and descriptions. Your screen reader will read each label name and its description text. + +**You are done when:** Your triage recommendation comment appears on your assigned challenge issue with all four fields filled in. + +### Completing Chapter 9: Submit Your Evidence + +Your triage recommendation comment is your evidence. Close your Chapter 9 challenge issue when done. If you also applied labels directly, mention that in your comment. + +### Expected Outcomes + +- Student can read an issue and recommend appropriate labels, milestone, and project placement. +- Student understands triage reasoning even without maintainer permissions. +- Student leaves a clear, reusable triage note that a maintainer could act on immediately. + +### If You Get Stuck + +1. Not sure which label to pick? Start with just one: `documentation`, `bug`, or `accessibility`. You can always add more. +2. Milestone is unclear? Write `none` and explain why - that is a valid triage decision. +3. Project board is unknown? Write `Needs Triage` - that is the correct default. +4. Not sure what the issue is about? Re-read the title and first paragraph. If still unclear, that itself is useful triage feedback ("Issue description is unclear - needs more detail"). +5. Ask facilitator to review your one-sentence reason before posting. + +### Learning Moment + +Triage is about clarity, not authority. You do not need maintainer permissions to help organize work. A clear recommendation saves maintainers time and speeds up collaboration. This is a skill used daily in open source. + +> **Continue learning:** The GitHub Skills course [Introduction to Repository Management](https://github.com/skills/introduction-to-repository-management) covers labels, milestones, and contributor settings in an interactive, self-paced format. See [Appendix Z](appendix-z-github-skills.md) for the full catalog. + +### Learning Pattern Used in This Chapter + +1. Inspect an issue carefully before acting (read before you write). +2. Classify work using a consistent vocabulary (labels, milestones). +3. Explain your reasoning in writing (one-sentence justification). +4. Build triage instincts that transfer to any open source project. + + +## Labels + +### What Are Labels? + +Labels are colored tags applied to issues and pull requests. They communicate at a glance what category, priority, or status an item belongs to. When you scan the issue list with your screen reader, labels are announced alongside each issue title. + +Labels are announced as: "Label: bug" or "Labels: accessibility, good first issue" depending on how many are applied. + +### Standard Labels You Will Find in Most Repos + +| Label | Purpose | +| ------- | --------- | +| `bug` | Something isn't working as expected | +| `enhancement` | A new feature or improvement | +| `documentation` | Changes or additions to documentation only | +| `good first issue` | Suitable for first-time contributors | +| `help wanted` | Maintainers are actively seeking community help | +| `question` | More information is needed before action | +| `invalid` | The issue doesn't meet the project's criteria | +| `wontfix` | The project won't address this (by design or out of scope) | +| `duplicate` | Another open issue covers the same topic | +| `accessibility` | Accessibility-related issue or change | +| `needs triage` | Not yet reviewed by a maintainer | + +### Navigating to the Labels Page + +From a repository: + +
    +Visual / mouse users + +Go to the **Issues** tab, then click the **Labels** link/button (it’s in the filter toolbar above the issue list, next to Milestones). The Labels page shows every label with its colour, name, and description. + +
    + +
    +Screen reader users (NVDA / JAWS - Windows) + +1. Navigate to the Issues tab +2. Press `K` to find the "Labels" link (near the "Milestones" link in the toolbar) +3. Press `Enter` + +
    + +
    +Screen reader users (VoiceOver - macOS) + +1. Navigate to the Issues tab +2. Quick Nav `K` to find the "Labels" link (near the "Milestones" link in the toolbar) +3. `VO+Space` to activate + +
    + +
    +GitHub CLI (gh) alternative - viewing labels + +List all labels in a repository from your terminal: + +```bash +# List all labels with descriptions +gh label list + +# List labels in a specific format +gh label list --json name,description +``` + +
    + +### Applying a Label to an Issue or PR + +### Tool Cards: Apply a Label + +**github.com (browser):** +1. Open the issue or PR. +2. In the right sidebar, click the gear icon next to **Labels**. +3. Select labels from the dropdown, then click outside to apply. + +**github.dev (web editor):** +Not available -- labels are managed on the issue/PR page, not in the code editor. + +**VS Code Desktop (GitHub Pull Requests extension):** +1. Open the issue in the **GitHub** sidebar panel. +2. Click the label area to add or remove labels. + +**GitHub Desktop:** +Not directly supported. Use **Repository > View on GitHub** to manage labels in the browser. + +**Git CLI / GitHub CLI:** +```bash +gh issue edit 42 --add-label "accessibility,good first issue" +gh pr edit 15 --add-label "documentation" +``` + +From an open issue or PR: + +
    +Visual / mouse users + +In the right sidebar, click the gear icon () next to **Labels**. A dropdown opens showing all labels. Click a label to apply it (a checkmark appears). Click outside to close - the label appears immediately on the issue. + +
    + +
    +Screen reader users (NVDA / JAWS - Windows) + +1. Navigate to the sidebar → press `H` or `3` to find the "Labels" heading +2. Activate the Labels gear/edit button (`B` until you hear "Labels" button → `Enter`) +3. Dropdown opens showing all available labels: use `↑/↓` to navigate +4. `Enter` to select or deselect a label; type to filter (e.g., type "access" to find "accessibility") +5. Press `Escape` to close - selections save automatically + +
    + +
    +Screen reader users (VoiceOver - macOS) + +1. `VO+U` → Headings or Quick Nav `H` to find the "Labels" heading in the sidebar +2. Quick Nav `B` to find the "Labels" gear/edit button → `VO+Space` +3. Dropdown opens: `VO+Down` or arrow keys to navigate labels +4. `VO+Space` to select or deselect; type to filter +5. `Escape` to close - selections save automatically + +
    + +
    +GitHub CLI (gh) alternative - applying labels + +Apply labels to issues or PRs from your terminal: + +```bash +# Add a label to an issue +gh issue edit 42 --add-label "accessibility" + +# Add multiple labels at once +gh issue edit 42 --add-label "bug,good first issue" + +# Remove a label +gh issue edit 42 --remove-label "needs triage" + +# Add a label to a PR +gh pr edit 42 --add-label "accessibility" +``` + +
    + +### Filtering Issues by Label + +
    +Visual / mouse users + +- **Using the filter button:** From the Issues list, click the **Label** dropdown button above the issue list, choose the label(s) you want, then click outside to apply. The active filter shows in the search bar. +- **Using the search bar:** Click in the search/filter bar and type `label:accessibility` (for example) along with any other filters. + +
    + +
    +Screen reader users (NVDA / JAWS - Windows) + +**Option A - Filter bar:** Press `F` → type `is:open label:accessibility` → `Enter` + +**Option B - Filter button:** `B` → "Label" dropdown button → `Enter` → `↑/↓` to choose → `Enter` → `Esc` + +**Option C - Combining labels:** `is:open label:accessibility label:"good first issue"` + +
    + +
    +Screen reader users (VoiceOver - macOS) + +**Option A - Filter bar:** Quick Nav `F` to find the search bar → `VO+Shift+Down` to interact → type `is:open label:accessibility` → `Return` + +**Option B - Filter button:** Quick Nav `B` → "Label" dropdown button → `VO+Space` → arrow keys to choose → `VO+Space` to select → `Esc` + +**Option C - Combining labels:** `is:open label:accessibility label:"good first issue"` + +
    + +
    +GitHub CLI (gh) alternative - filtering by label + +Filter issues by label from your terminal: + +```bash +# List issues with a specific label +gh issue list --label "accessibility" + +# Combine multiple labels +gh issue list --label "accessibility" --label "good first issue" + +# Combine with state filter +gh issue list --label "accessibility" --state closed + +# Search across labels +gh issue list --search "label:accessibility label:\"good first issue\"" +``` + +
    + +### Creating a New Label + +If you have write access: + +1. Navigate to Issues → Labels page +2. Tab to "New label" button → Enter +3. Fill in: Label name (F for form field), Color (use the color picker or hex code), Description +4. Tab to "Create label" button → Enter + +
    +GitHub CLI (gh) alternative - creating labels + +Create labels from your terminal: + +```bash +# Create a new label +gh label create "accessibility" --description "Accessibility-related issue" --color "0075ca" + +# Create with a specific color +gh label create "in progress" --description "Being actively worked on" --color "e4e669" +``` + +
    + +**Accessibility note for color:** Labels have color, but they also have a text name and description - the color is supplementary information. Screen readers announce the label name, not the color, so labels are fully accessible. + +### Learning Cards: Labels + +
    +Screen reader users + +- On the Issues list, labels are announced alongside each issue title: "Label: bug" or "Labels: accessibility, good first issue" +- Press `L` on an open issue (Focus Mode) to open the label picker directly; type to filter, `Down Arrow` to navigate, `Enter` to select +- When filtering issues by label, type `is:open label:accessibility` in the search bar and press `Enter`; the list updates to show only matching issues + +
    + +
    +Low vision users + +- Labels appear as colored rounded rectangles next to issue titles in the list; in Windows High Contrast mode, labels use system border colors with readable text +- The Label dropdown from the sidebar gear icon is searchable: type the first few letters of a label name to filter the long list +- On the Labels management page (Issues tab, then Labels link), each label row shows its color swatch, name, and description in a table-like layout + +
    + +
    +Sighted users + +- Labels appear as small colored pills next to issue titles in the Issues list; hover over a label to see its description in a tooltip +- Click the gear icon next to Labels in the issue sidebar to open a searchable dropdown; a checkmark appears next to selected labels +- The filter bar shows active label filters as text (e.g., `label:accessibility`); remove a filter by clicking the X next to it or clearing the search text + +
    + + +## Milestones + +### What Are Milestones? + +Milestones group issues and PRs toward a shared goal or deadline. Think of a milestone as a sprint, a version release, or an event (like "Hackathon Day 1 Deliverables"). A milestone shows: + +- A title and optional description +- An optional due date +- A progress bar (percentage of closed issues vs total) + +### Navigating to Milestones + +From Issues tab: + +1. Press `K` to find the "Milestones" link → Enter +2. You see a list of milestones, each with its title, progress, and due date + +#### Reading a milestone + +Each milestone is announced as a heading + progress information: + +- "Hackathon Day 1 Deliverables, 3 of 8 issues closed, due April 20" + +### Opening a Milestone + +1. Press `3` to navigate milestone titles (they are h3 links) +2. Press `Enter` to open a milestone +3. The milestone detail page shows all issues and PRs belonging to it +4. Navigate the list with `3` (issue titles) or `I` (list items) + +### Adding an Issue to a Milestone + +
    +Visual / mouse users + +From the open issue, find the **Milestone** section in the right sidebar and click the gear icon. A dropdown lists available milestones - click one to assign it. + +
    + +
    +Screen reader users (NVDA / JAWS - Windows) + +1. Navigate to the sidebar → "Milestone" heading (`H` or `3`) +2. Activate the Milestone gear button +3. Select a milestone from the dropdown (`↑/↓` → `Enter`) +4. `Esc` to close + +
    + +
    +Screen reader users (VoiceOver - macOS) + +1. Quick Nav `H` or `VO+Cmd+H` to find the "Milestone" heading in the sidebar +2. Quick Nav `B` to find and activate the Milestone gear button (`VO+Space`) +3. Select a milestone from the dropdown (`VO+Down` or arrow keys → `VO+Space`) +4. `Esc` to close + +
    + +
    +GitHub CLI (gh) alternative - milestones + +Manage milestones from your terminal: + +```bash +# Assign an issue to a milestone +gh issue edit 42 --milestone "Hackathon Day 1" + +# Remove from a milestone +gh issue edit 42 --milestone "" + +# List issues in a milestone +gh issue list --milestone "Hackathon Day 1" +``` + +**Note:** Creating milestones requires the web interface or the GitHub API - the `gh` CLI does not have a `milestone create` command. Use `gh api` for advanced operations: + +```bash +gh api repos/{owner}/{repo}/milestones -f title="Hackathon Day 1" -f description="Day 1 deliverables" +``` + +
    + +### Creating a Milestone + +Requires write access: + +1. Navigate to Milestones page +2. Tab to "New milestone" button → Enter +3. Fill in: Title, Description, Due date (optional) +4. Tab to "Create milestone" → Enter + +**Due date field note:** The date field may render as a date picker. You can: + +- Type the date in `YYYY-MM-DD` format directly (most reliable) +- Or use arrow keys to adjust month/day/year if spin buttons are provided +- Or press `Space` or `Enter` to open a calendar widget (if your screen reader supports it) and arrow through dates + +Screen readers handle date pickers inconsistently - typing the date is most reliable across browsers. + +### Learning Cards: Milestones + +
    +Screen reader users + +- On the Milestones page, each milestone is an H3 heading link; it announces the title, progress ("3 of 8 issues closed"), and due date +- Press `Enter` on a milestone heading to open it; the detail page lists all assigned issues, navigable with `3` for titles or `I` for list items +- To assign an issue to a milestone, navigate to the sidebar "Milestone" heading (`H`), activate the gear button, then use `Up/Down Arrow` to select + +
    + +
    +Low vision users + +- Each milestone row shows a progress bar (green fill) and a fraction like "3 / 8" next to the title; the bar is visible at any zoom level +- The due date appears as grey text to the right of the progress bar; at high zoom it may wrap below the title +- The due date field when creating a milestone accepts typed input in YYYY-MM-DD format, which is more reliable than using the date picker at high magnification + +
    + +
    +Sighted users + +- Milestones are listed on the Milestones page (accessible from the Issues tab, via the "Milestones" link in the toolbar) +- Each milestone shows a green progress bar, an issue count (e.g., "3 of 8"), an optional due date, and a description +- When viewing an issue, the assigned milestone appears in the right sidebar; click the milestone name to see all issues in that milestone + +
    + + +## Cross-References + +Cross-references are links between issues, PRs, and commits. GitHub automatically renders `#42` as a link to issue or PR #42. This creates a web of context so any contributor can trace the history of a decision. + +### Types of Cross-References + +| Syntax | Effect | +| -------- | -------- | +| `#42` | Links to issue or PR #42 in the same repo | +| `owner/repo#42` | Links to issue #42 in a different repository | +| `a1b2c3d` | Links to a specific commit by its SHA hash | +| `@username` | Notifies and links to a GitHub user's profile | +| `Closes #42` | Closes issue #42 when the PR merges | +| `Fixes #42` | Same as Closes - conventional for bugs | +| `Resolves #42` | Same as Closes - general use | +| `Refs #42` | Links without auto-closing | + +### Typing a Cross-Reference + +Inside any comment or PR description text area (Focus Mode): + +1. Type `#` - a live-search dropdown appears +2. Continue typing the issue number or title fragment +3. Use `↓` to navigate the dropdown → `Enter` to select +4. The `#42` link is inserted automatically + +For `@mentions`: + +1. Type `@` followed by a username +2. A dropdown of suggestions appears +3. `↓` to navigate → `Enter` to select + +### When the "Closes" Keyword Fires + +The `Closes #42` keyword must appear in: + +- The **PR description** (body text) +- A **commit message** pushed to the default branch + +It does **not** fire from comments on the PR. If you write "Closes #42" in a comment, it creates a reference but does not auto-close the issue on merge. + +### Learning Cards: Cross-References + +
    +Screen reader users + +- Type `#` in any comment box (Focus Mode) to trigger a live-search dropdown of issues and PRs; press `Down Arrow` to navigate, `Enter` to insert the reference +- Type `@` followed by a username to trigger user autocomplete; press `Down Arrow` and `Enter` to insert the mention +- After a PR merges with `Closes #42` in the description, navigate to issue 42 and press `3` to find the "Closed by #XX" cross-reference comment + +
    + +
    +Low vision users + +- Cross-reference links (`#42`, `@username`) render as blue clickable text in comments; they are distinct from surrounding text at any zoom level +- GitHub adds automatic back-links when you reference an issue or PR; look for them as timeline events (small text between comments) on the referenced item +- The `Closes #42` keyword in a PR description renders as a clickable link to the issue, with a small icon showing the issue's current state + +
    + +
    +Sighted users + +- Typing `#` in a comment box opens a dropdown showing matching issues and PRs with their number, title, and open/closed state +- Cross-references create bidirectional links: issue 42 gets a timeline event "Referenced in PR #25" and the PR shows "Closes #42" as a clickable link +- Use `Closes #42`, `Fixes #42`, or `Resolves #42` in the PR description body (not in comments) to trigger automatic issue closure on merge + +
    + + +## GitHub Projects + +> **See also:** [Appendix R: Projects Deep Dive](appendix-r-projects-deep-dive.md) covers advanced project board configuration, custom fields, and automation. + +### What Is a GitHub Project? + +GitHub Projects is a built-in project management tool. It can display issues and PRs from across multiple repositories in one view. Projects support three layouts: + +| Layout | Description | Best For | +| -------- | ------------- | ---------- | +| **Table** | Spreadsheet-style with custom fields | Tracking detailed status | +| **Board** | Kanban columns (Todo, In Progress, Done) | Visual workflow | +| **Roadmap** | Timeline/Gantt view | Planning across time | + +### Finding a Project + +From an organization page or repository: + +1. Navigate to the "Projects" tab +2. Press `3` to navigate project titles (they are h3 links) +3. `Enter` to open a project + +### Navigating a Project - Table View + +```text +Step 1: The main content is a large grid/table +Step 2: T to jump to the table +Step 3: Ctrl+Alt+↓ to navigate rows (each row is an issue or PR) +Step 4: Ctrl+Alt+→ to navigate columns (Title, Status, Priority, etc.) +Step 5: Enter on a row to open the issue/PR detail panel +``` + +#### What is announced per row + +"Add keyboard navigation to carousel | Status: In Progress | Assignee: username | Priority: High" + +### Navigating a Project - Board View + +```text +Step 1: Switch to Board view using the view selector button +Step 2: Each column (Todo / In Progress / Done) is a region +Step 3: D to navigate between column landmarks +Step 4: Within a column: 3 to navigate card titles, I for list items +Step 5: Enter on a card to open the issue/PR panel +``` + +### Adding an Issue to a Project + +From an open issue: + +1. Navigate to the sidebar "Projects" section (`H` or `3`) +2. Activate the Projects gear button +3. Select the project from the dropdown + +Or from within a project: + +1. Activate "Add item" button at the bottom of a column/table +2. Type `#` to search for existing issues +3. Select the issue → it's added to the project + +### Learning Cards: GitHub Projects + +
    +Screen reader users + +- In Table view, press `T` to jump to the project table, then use `Ctrl+Alt+Down Arrow` for rows and `Ctrl+Alt+Right Arrow` for columns (Title, Status, Priority, Assignee) +- In Board view, press `D` to navigate between column landmarks (Todo, In Progress, Done), then `3` to jump between card titles within a column +- Press `Enter` on any card or table row to open the issue/PR detail panel without leaving the project view + +
    + +
    +Low vision users + +- Board view shows issues as cards in vertical columns (Todo, In Progress, Done); each card displays the title, assignee avatar, and labels +- Table view is wider and has more columns; at high zoom, use horizontal scrolling to see columns like Priority and Assignee +- The view selector button (Table/Board/Roadmap) is near the top of the project page; it uses icon buttons that have text labels on hover + +
    + +
    +Sighted users + +- Switch between Table, Board, and Roadmap views using the view selector buttons at the top of the project page +- Board view: drag and drop cards between columns, or click the Status field on a card to change it without dragging +- Table view: click column headers to sort, use the "+" button to add custom fields (Priority, Estimate, etc.), and click a row to open the issue detail panel + +
    + + +## Practical Organization Strategy for the Hackathon + +Here is a recommended structure for your Learning Room sandbox project: + +### Labels to create + +```text +accessibility - all a11y-related work +documentation - docs-only changes +good first issue - for new contributors +in progress - being actively worked on +needs review - PR is open, review needed +blocked - waiting on something external +help wanted - community assistance requested +``` + +### Milestone to create + +```text +Name: Hackathon Day 1 Deliverables +Due: [Day 1 date] +Description: All contributions made during Day 1 of the Open Source AT Hackathon +``` + +### Workflow + +```text +1. File an issue → add label + milestone +2. Comment "I'll work on this" → add "in progress" label +3. Make changes → open PR → link to issue +4. PR merged → issue closes automatically → milestone progress updates +``` + + +## Try It: Label and Link + +**Time:** 2 minutes | **What you need:** Browser, signed in to GitHub + +Go to the Learning Room repository and do two things: + +1. **Add a label to an issue** - Open any issue (press `G` then `I`, then `Enter` on an issue title). Press `L` (in Focus Mode) to open the label picker. Type `documentation` to filter, then press `Enter` to apply it. Press `Esc` to close. +2. **Use a cross-reference** - Leave a comment on that issue mentioning another issue number: `Related to #1` (or any issue number you've seen). Press `Ctrl+Enter` to submit. + +**You're done.** You just organized work using labels and connected two issues with a cross-reference. + +> **What success feels like:** The label now appears on the issue, and your cross-reference is a clickable link that connects the two issues. That's project management on GitHub - and you did it in under two minutes. + + +> ### Day 2 Amplifier - Accessibility Agents: `@issue-tracker` with Labels +> +> **Apply labels and milestones manually in today's exercises before using any agent.** Labels are the language that automation uses to filter, route, and prioritize work. If you have not designed and applied them yourself, you cannot configure them correctly for automated use - and you cannot tell when automation is applying the wrong ones. +> +> Once you have mastered manual organization: +> +> - **In VS Code** - `@issue-tracker find open issues labeled accessibility, severity-high` uses the exact label vocabulary you configured today, delivering prioritized cross-repository results with community engagement and release-impact scoring +> - **In your repo** - Accessibility Agents forks carry the label schema in `.github/ISSUE_TEMPLATE/`; your project's organizational language travels with every clone and does not require manual recreation +> - **In the cloud** - GitHub Agentic Workflows apply labels automatically when issues are opened, routing work into the right milestone and Project view without manual triage on every item - but only if your labels were designed with clear, consistent intent +> +> *Labeling today is not overhead. It is configuring the input layer that every agent downstream depends on.* + + +> **Next Step:** Move on to [Chapter 10: Notifications](10-notifications-and-day-1-close.md) to finish Day 1. + +--- + + +*Next: [Chapter 10: Notifications and Day 1 Close](10-notifications-and-day-1-close.md)* +*Back: [Chapter 08: Open Source Culture](08-open-source-culture.md)* +*Related appendices: [Appendix R: Projects Deep Dive](appendix-r-projects-deep-dive.md)* + + + diff --git a/admin/qa-bundle/docs/10-notifications-and-day-1-close.md b/admin/qa-bundle/docs/10-notifications-and-day-1-close.md new file mode 100644 index 0000000..fb441a1 --- /dev/null +++ b/admin/qa-bundle/docs/10-notifications-and-day-1-close.md @@ -0,0 +1,701 @@ +# Notifications +> +> **Listen to Episode 10:** [Notifications and Mentions](../admin/PODCASTS.md) - 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-t-community-and-social.md) | [Appendix U: Discussions and Gists](appendix-u-discussions-and-gists.md) | [Appendix V: GitHub Mobile](appendix-v-github-mobile.md) +> **Authoritative sources:** [GitHub Docs: About notifications](https://docs.github.com/en/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/about-notifications) + + +## Managing Your GitHub Notification Inbox + +> **See also:** [Appendix V: GitHub Mobile](appendix-v-github-mobile.md) 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 + +### Chapter 10 Challenge Set + +1. **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. + +1. Open your Learning Room repository on GitHub.com. +2. Find the **Watch** button near the top-right of the repository page (next to Star and Fork). +3. 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. +4. Open the notifications inbox by navigating to `https://github.com/notifications` (or activate the bell icon in the GitHub header). +5. In the notification filters, activate the **Review requested** filter. This shows only notifications where someone has asked you to review their PR. +6. Clear that filter and activate the **Assigned** filter. This shows notifications for issues and PRs assigned to you. +7. Open one notification by activating its title link. Read it briefly, then navigate back to the inbox. +8. 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: + +```text +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 + +1. Can't find the Watch button? It is near the top-right of the repository page, in the same row as Star and Fork. +2. Notification inbox is empty? You may not have any notifications yet - that is fine. Switch to the **Done** tab and practice the mute/done action flow on an older notification. +3. Keyboard shortcuts not working? If your screen reader intercepts `M` or `E`, click on the notification row first to give it focus, then press the shortcut. +4. Filters not showing results? Clear all filters first (click the X next to each active filter), then apply one filter at a time. +5. Ask facilitator to model one inbox action live, then repeat the steps yourself. +6. Finished but not sure you did it right? Compare your work against the [Challenge 9 reference solution](solutions/solution-09-merge-day.md). + +### Learning Moment + +Notification management protects focus. You can stay responsive to your team without drowning in updates. The habit you build here - checking filtered notifications once or twice a day - is how productive open source contributors stay on top of their work. + +### Learning Pattern Used in This Chapter + +1. Configure settings proactively (watch level) before work generates noise. +2. Use filters to find signal in noise (review requests, assignments). +3. Take decisive action on each notification (mute, done, or respond). +4. Build a daily routine that keeps your inbox manageable. + + +## What Generates a Notification? + +GitHub sends you a notification when: + +| Event | You are notified if... | +| ------- | ------------------------ | +| Someone @mentions you | `@your-username` appears in any issue, PR, or discussion | +| A PR is assigned to you for review | You are added as a reviewer | +| An issue or PR is assigned to you | You are assigned | +| There is activity on a thread you are subscribed to | You commented, were mentioned, or chose to subscribe | +| A CI check fails on your PR | Actions sends a failure notification | +| A release is published | You are watching the repo for all activity | + + +## Notification Subscription Levels + +For each repository, you choose how many notifications to receive: + +| Level | What You Receive | +| ------- | ----------------- | +| **Participating and @mentions** | Only notifications where you participated (commented, were assigned, @mentioned). Recommended for most repos. | +| **All Activity** | Every issue opened, every comment, every PR. Only use this for your own repos or very active contribution. | +| **Ignore** | No notifications from this repo at all. | +| **Custom** | Fine-grained control: issues only, PRs only, releases, etc. | + +### Changing your watch settings for a repo + +
    +Visual / mouse users + +At the top of any repository page, find the **Watch** button (near Star and Fork). Click it to open a dropdown with levels: **Participating and @mentions**, **All Activity**, **Custom**, and **Ignore**. Click your preferred level - it takes effect immediately. + +
    + +
    +Screen reader users (NVDA / JAWS - Windows) + +1. Find the **Watch** button in the repo header (`B` to navigate buttons → find "Watch [N]" or "Unwatch" button) +2. Press `Enter` to open the dropdown +3. Press `↑/↓` to navigate the subscription options +4. Press `Enter` to select your preferred level +5. The button label updates to confirm your choice + +
    + +
    +Screen reader users (VoiceOver - macOS) + +1. Quick Nav `B` to find the **Watch** button in the repo header (listen for "Watch" or "Unwatch") +2. `VO+Space` to open the dropdown +3. `VO+Down` or arrow keys to navigate subscription options +4. `VO+Space` to select your preferred level +5. The button label updates to confirm your choice + +
    + +**Recommended setting for most repos:** “Participating and @mentions only” - you stay in the loop on what involves you without noise. + + +## The Notifications Inbox + +### Tool Cards: Manage Notifications + +**github.com (browser):** +1. Go to [github.com/notifications](https://github.com/notifications) (or press `G` then `N`). +2. Use `E` to mark done, `I` to mark read/unread, `Shift+M` to mute a thread. + +**VS Code Desktop (GitHub Pull Requests extension):** +1. The **Notifications** view in the GitHub sidebar shows items needing attention. +2. Click a notification to open the related issue or PR directly in VS Code. + +**GitHub Desktop:** +GitHub Desktop does not manage notifications. Use the browser or CLI. + +**Git CLI / GitHub CLI:** +```bash +# List PRs requesting your review (most common notification) +gh search prs --review-requested @me --state open +# Open the notifications page in your browser +gh browse notifications +``` + +Navigate to your inbox: `https://github.com/notifications` or press `G` then `N` (GitHub keyboard shortcut). + +**Screen reader note:** The `G N` shortcut uses two sequential key presses (not simultaneous). Press `G`, release it, then press `N`. This works in Browse Mode. + +
    +GitHub CLI (gh) alternative - notifications + +View and manage your GitHub notification status from the terminal: + +```bash +# Check your notification status (opens the GitHub notification inbox) +gh api notifications --jq '.[].subject.title' | head -20 + +# View PRs that need your review (most common notification reason) +gh search prs --review-requested @me --state open + +# View issues assigned to you +gh issue list --assignee @me --state open + +# Check PR status for a specific notification +gh pr view 42 --repo owner/repo +``` + +**Note:** The GitHub CLI does not have a first-class `gh notifications` command. For full inbox management (mark as read, mute, archive), use the web interface at `github.com/notifications`. The `gh` CLI is most useful for quickly checking PR review requests and issue assignments that generate notifications. + +
    + +### Page structure + +```text +[Filters sidebar on left] ← Unread / Participating / @Mentions / Assigned / etc. +[Notification list in center] ← Each notification is a row +[Detail pane on right] ← Preview the notification (can be disabled) +``` + +### Navigating the notification list + +
    +Visual / mouse users + +The inbox shows notifications grouped by date (Today, Yesterday, This week, Older). Each row shows the repository, the issue or PR title, the event type, and the time. Click a row to open the notification and go to the issue or PR. Use the left sidebar filters to narrow the view. The **Mark all as done** button clears the entire inbox at once. + +
    + +
    +Screen reader users (NVDA / JAWS) + +1. `D` → main content landmark +2. `H` to navigate group headings (Today / Yesterday / This week / Older) +3. `Tab` through individual notifications - each row announces: repo name, issue/PR title, event type, time +4. `Enter` to open the notification (goes to the issue/PR page) + +
    + +
    +Screen reader users (VoiceOver) + +1. `VO+U` → Main → navigate to notification list +2. `VO+Down` to move through notifications +3. `VO+Space` to open a notification + +
    + +### What is announced per notification + +> "microsoft/vscode - Add keyboard shortcut for accessible view - @username mentioned you - 2 hours ago" + +Components: **repo/org** | **thread title** | **event type** | **timestamp** + +### Learning Cards: The Notifications Inbox + +
    +Screen reader users + +- Press `G N` (two sequential keys, not simultaneous) from any GitHub page to jump directly to your notifications inbox +- Press `H` to navigate date-group headings (Today, Yesterday, This Week, Older), then `Tab` through individual notification rows within each group +- Each notification row announces: repository name, issue/PR title, event type (mentioned, review requested, assigned), and relative timestamp + +
    + +
    +Low vision users + +- The inbox has a three-panel layout: filters on the left, notification list in the center, and an optional detail preview on the right; at high zoom the detail pane may collapse +- Unread notifications have a blue dot on the left edge of the row; read notifications do not, which is the primary visual distinction +- The left sidebar filter labels (Inbox, Unread, Saved, Done) are text links that remain readable at any zoom level + +
    + +
    +Sighted users + +- The notifications inbox at github.com/notifications shows a list of notifications grouped by date, with a filter sidebar on the left +- Unread notifications have a blue dot indicator; click a notification row to open the issue or PR in context +- Quick actions appear on hover: a checkmark icon to mark as done, a bookmark icon to save for later, and a mute icon to unsubscribe from the thread + +
    + + +## Inbox Actions - Keyboard Shortcuts + +These shortcuts work when a notification is focused in the inbox: + +| Shortcut | Action | +| ---------- | -------- | +| `E` | Mark as done (archive from inbox) | +| `Shift+I` | Mark as read without opening | +| `Shift+U` | Mark as unread | +| `M` | Mute thread (no more notifications from this thread) | +| `S` | Save for later | +| `Enter` | Open the notification | + +> **Screen reader note:** These are GitHub's own keyboard shortcuts. In Browse Mode, some of these letters are also navigation keys. To use these shortcuts reliably, make sure focus is on the notification row (tab to it) rather than in browse/reading mode. + + +## Filtering the Inbox + +The left sidebar has quick filters. Use `Tab` or `K` to navigate to them: + +| Filter | Shows | +| -------- | ------- | +| Inbox | All active notifications (default) | +| Unread | Only unread notifications | +| Saved | Notifications you saved with `S` | +| Done | Archived (marked done) notifications | +| @Mentioned | Only threads where you were directly @mentioned | +| Assigned | Issues and PRs assigned to you | +| Review requested | PRs where your review is requested | +| Participating | All threads you participated in | + +### Filtering by repository or organization + +At the top of the notification list there is a filter/search field: + +
    +Visual / mouse users + +Click the filter/search box at the top of the notification list and type a repository or organization name. The list narrows in real time. Press `Escape` or clear the box to reset. + +
    + +
    +Screen reader users (NVDA / JAWS - Windows) + +1. Press `F` or `E` to reach the filter input +2. Focus Mode → type repo name or org name +3. Results filter in real time +4. Press `Esc` to clear the filter + +
    + +
    +Screen reader users (VoiceOver - macOS) + +1. Quick Nav `F` to reach the filter input +2. `VO+Shift+Down` to interact → type repo or org name +3. Results filter in real time +4. Press `Esc` to clear the filter and `VO+Shift+Up` to stop interacting + +
    + + +## Managing Notifications at Scale + +### The "mark all as done" workflow + +After a busy day or coming back from time away, clear your inbox methodically: + +1. Open Notifications inbox +2. Tab to "Mark all as done" button → Enter (clears everything at once) +3. Then use the "Done" filter to retrieve any you want to revisit + +### Muting a noisy thread + +If a thread generates too many notifications: + +
    +Visual / mouse users + +1. Open the issue or PR page +2. In the right sidebar, scroll to the **Notifications** section +3. Click **Unsubscribe** - you will stop receiving notifications from this thread +4. Alternatively, from the inbox: hover over the notification row and click the **mute** icon (or the … menu) + +
    + +
    +Screen reader users (NVDA / JAWS - Windows) + +1. Open the notification +2. On the issue/PR page, navigate the sidebar to the **Notifications** section (`H` or `D`) +3. Activate the **Unsubscribe** button +4. Or from the inbox: focus the notification → press `M` to mute + +
    + +
    +Screen reader users (VoiceOver - macOS) + +1. Open the notification +2. On the issue/PR page, `VO+U` → Landmarks or Quick Nav `H` to find the **Notifications** section in the sidebar +3. Quick Nav `B` or `Tab` to find the **Unsubscribe** button → `VO+Space` +4. Or from the inbox: focus the notification and press `M` to mute + +
    + +### Dealing with @mentions you didn't expect + +If you were @mentioned in an unfamiliar thread: + +1. Read the thread for context before responding +2. If it seems like a mistake, a simple "I don't think this mention was meant for me - feel free to remove it!" is enough +3. Unsubscribe after reading if you don't need to stay in the loop + +### Learning Cards: Managing Notifications at Scale + +
    +Screen reader users + +- To mute a noisy thread from the inbox, focus the notification row with `Tab` and press `M`; you will stop receiving updates from that thread +- Press `E` to mark a focused notification as done (archived); focus automatically moves to the next notification for rapid triage +- To bulk-clear, Tab to the "Mark all as done" button at the top of the inbox and press `Enter`; then use the "Done" filter to retrieve anything you need later + +
    + +
    +Low vision users + +- The "Mark all as done" button is at the top of the notification list, above the first notification group; it clears the entire inbox at once +- After marking notifications as done, switch to the "Done" filter in the left sidebar to review archived items; this filter persists until you switch back +- On an issue or PR page, the "Unsubscribe" button is in the right sidebar under a "Notifications" heading; it prevents future notifications from that thread + +
    + +
    +Sighted users + +- Hover over any notification row to reveal quick-action icons: checkmark (done), bookmark (save), and mute (unsubscribe) +- Use the "Mark all as done" button to clear the entire inbox, then revisit important items via the "Done" filter in the left sidebar +- On an issue/PR page, the "Unsubscribe" link in the sidebar Notifications section stops notifications for that specific thread without unwatching the entire repository + +
    + + +## Notification Settings - Per Your Account + +Global notification preferences are at `https://github.com/settings/notifications`. + +Key settings to review: + +| Setting | Recommendation | +| --------- | --------------- | +| **Email delivery** | Choose Participating and @mentions unless you prefer email for everything | +| **GitHub Mobile** | Enable only if you use GitHub Mobile - mobile notifications can duplicate desktop ones | +| **Watching** | "Participating and @mentions" unless you are an active maintainer | +| **Organization alerts** | Enable for orgs where you have responsibilities | + +Navigate this settings page: + +```text +H → navigate to each settings section heading +F or E → navigate form fields within each section +Tab → move between options within a form group +``` + + +## Starring vs. Watching - What Is the Difference? + +New contributors often confuse these two. They appear next to each other on every repository page and do completely different things. + +### Starring a Repository + +| Feature | Description | +| --- | --- | +| **What it does** | Bookmarks the repository to your Stars list at `github.com/stars` | +| **Notifications** | **None.** Starring never sends you any notifications | +| **Visibility** | Public - anyone can see what you've starred on your profile | +| **Use case** | "I want to save this for later" or "I want to show appreciation" | +| **Keyboard path** | On any repo page: `B` to navigate buttons → find "Star" button → Enter | + +Starring is GitHub's equivalent of a bookmark + public endorsement. The star count on a repository is a community signal of popularity. Many maintainers watch their star count as a rough measure of interest. + +### Watching a Repository + +| Feature | Description | +| --- | --- | +| **What it does** | Subscribes you to notifications from that repository | +| **Notifications** | Sends notifications based on your chosen level (see below) | +| **Visibility** | Private - other users cannot see what you're watching | +| **Use case** | "I need to stay informed about activity in this repo" | +| **Keyboard path** | `B` → find "Watch" button → Enter → ↑/↓ to pick a level → Enter | + +### Common Mistake: Accidental Watching + +When you comment on an issue or PR in a repository, GitHub **automatically subscribes you** to that thread - but not the whole repository. However, if you once click "Watch" on a busy repository (say, a popular open source project), you will receive a notification for every issue opened and every comment posted - potentially hundreds per day. + +#### How to silence a repository you accidentally over-subscribed to + +```text +Step 1: Navigate to the repository +Step 2: B → Find "Unwatch" button → Enter +Step 3: Select "Participating and @mentions" +Step 4: Enter to confirm +``` + +This immediately reduces notifications from that repository to only threads you personally participated in. + +### Recommended Watching Strategy for This Workshop + +| Repository | Recommended Watch Level | +| --- | --- | +| `community-access/accessibility-agents` | **Participating and @mentions** - you contribute there, you only need to hear back when someone replies to you | +| Your own fork | **All Activity** - this is your fork; know everything | +| Very busy popular repos | **Ignore** or **Participating** - do not watch for All Activity | +| Repos you're evaluating | **Star only** - save without subscribing | + +### Learning Cards: Starring vs. Watching + +
    +Screen reader users + +- The Star and Watch buttons are adjacent in the repository header; press `B` to navigate buttons and listen for "Star" or "Watch" (or "Unstar" / "Unwatch" if already active) +- Star: press `Enter` on the Star button to bookmark; this generates zero notifications and is purely a bookmark to github.com/stars +- Watch: press `Enter` on the Watch button to open a dropdown; use `Up/Down Arrow` to choose a subscription level and `Enter` to confirm + +
    + +
    +Low vision users + +- The Star button shows a star icon and a count (e.g., "Star 1.2k"); the Watch button shows an eye icon and a count; both are in the top-right area of the repository page +- After starring, the button changes to "Unstar" with a filled yellow star; after watching, it changes to "Unwatch" with a filled eye icon +- At 200%+ zoom, these buttons may wrap below the repository title; they remain functional at any zoom level + +
    + +
    +Sighted users + +- Star (star icon) = bookmark only; Watch (eye icon) = subscribe to notifications; they are next to each other and next to the Fork button in the repo header +- Star counts are public and show on your profile; watch settings are private and affect only your notification inbox +- If you accidentally watched a busy repo and are flooded with notifications, click Unwatch and switch to "Participating and @mentions" to reduce noise immediately + +
    + + +## Screen Reader Tips for the Notification Inbox + +### NVDA + +- The notification list is complex - use `Tab` to navigate individual rows rather than Browse Mode arrow keys +- After marking notifications done (press `E`), the next notification automatically receives focus +- Use `NVDA+F7` → Links to get a filtered list of notification titles to scan quickly + +### JAWS + +- Like NVDA, use `Tab` for row navigation in the inbox +- `Insert+F6` (Headings list) to jump between date group headings (Today, This Week, etc.) +- The inbox updates in real time - JAWS will announce new notifications as they arrive + +### VoiceOver + +- Use `VO+U` → Landmarks → Main to reach the notification list quickly +- `VO+Space` to activate a row, `VO+Escape` to return to the list +- With Quick Nav on, `H` navigates the date group headings + + +## The GitHub Mobile App - A Reference Note + +GitHub has an iOS and Android app that supports push notifications. While the app itself is not covered as a primary tool in this workshop, it is worth knowing: + +- Push notifications can alert you to review requests even when you're away from your computer +- The mobile app does work with iOS VoiceOver and Android TalkBack +- For primary contribution work, the desktop browser experience remains more fully featured + + +## Try It: Tame Your Inbox + +**Time:** 2 minutes | **What you need:** Browser, signed in to GitHub + +Go to [github.com/notifications](https://github.com/notifications) and practice: + +1. **Scan your inbox** - Press `H` and `Tab` to navigate through notifications. Each one shows the repo name, type (issue/PR), and title. +2. **Mark one as done** - Find a notification you've already read. Press `E` to mark it as done. It disappears from the list. +3. **Configure watching** - Go to the Learning Room repository. Press `D` to landmarks, find the repo nav area, then look for the "Watch" or "Unwatch" button (`B` to scan buttons). Choose your preferred watch level. + +**You're done.** You now control what GitHub tells you about and what it doesn't. + +> **What success feels like:** Your inbox has fewer items, and you chose what to watch. Notifications work *for* you now, not against you. + + +> ### Day 2 Amplifier - Accessibility Agents: `@daily-briefing` +> +> **Manage your notification inbox manually before using any agent.** The signal-versus-noise judgment you develop - what to act on, what to watch, what to mute - is the same judgment the agent applies when prioritizing its output. Without that judgment, you cannot evaluate whether the agent's prioritization is correct or whether it surfaced the things that actually matter to you. +> +> Once you have mastered manual notification management: +> +> - **In VS Code** - `@daily-briefing morning briefing` delivers the same information as your notification inbox, organized by priority and actionability, with the ability to reply, close, and merge from inside Copilot Chat +> - **In your repo** - Fork [accessibility-agents](https://github.com/Community-Access/accessibility-agents) and every collaborator on your project can run `@daily-briefing` against your shared repository; the whole team stays aligned from a single command with no inbox required +> - **In the cloud** - GitHub Agentic Workflows can run on a schedule and post a team digest to a designated issue each morning, surfacing what needs attention before anyone opens their notifications +> +> *Your notification discipline today becomes the standard the agent enforces at scale tomorrow.* + + +## What You Accomplished Today + +Take a breath. Day 1 is complete -- and you did a lot. + +Here is every skill you practiced, mapped to the chapter where you learned it and the evidence you created along the way: + +| Chapter | Skill | Evidence | +|---|---|---| +| [Chapter 00](00-pre-workshop-setup.md) | Created a GitHub account and configured accessibility settings | Account exists, profile is visible | +| [Chapter 01](01-choose-your-tools.md) | Chose your editing environment and tested it | Tool preference noted in your challenge issue | +| [Chapter 02](02-understanding-github.md) | Understood what GitHub is, how repositories work, and what collaboration looks like | Completion comment on challenge issue | +| [Chapter 03](03-navigating-repositories.md) | Navigated a real repository using keyboard and screen reader | Found specific files and folders in the Learning Room | +| [Chapter 04](04-the-learning-room.md) | Opened the Learning Room, found your challenge issues, and understood the workflow | First structured comment posted | +| [Chapter 05](05-working-with-issues.md) | Created, labeled, and commented on issues | Issue created with a descriptive title and body | +| [Chapter 06](06-working-with-pull-requests.md) | Created a branch, edited a file, and opened a pull request | Merged PR visible in the repository | +| [Chapter 07](07-merge-conflicts.md) | Recognized a merge conflict and resolved it | Conflict-free merge committed | +| [Chapter 08](08-open-source-culture.md) | Read contributing guidelines, understood community norms, and practiced respectful communication | Thoughtful comment on a peer's issue or PR | +| [Chapter 09](09-labels-milestones-projects.md) | Used labels, milestones, and project boards to organize work | Labels applied, milestone progress visible | +| [Chapter 10](10-notifications-and-day-1-close.md) | Configured notification preferences and managed your inbox | Watch level set, at least one notification acted on | + +That is eleven chapters, eleven skills, and a trail of real evidence in a real repository. + +### If This Was Your First Time + +If today was your first time using GitHub -- or your first time using it with a screen reader -- you have already done something most developers take weeks to piece together on their own. You navigated a complex platform, created real contributions, and collaborated with other people in a shared codebase. That is not a small thing. + +If parts felt confusing or slow, that is completely normal. Every skill you practiced today gets faster with repetition. The point was never speed -- it was understanding. + +### Confidence Check + +Before you close your laptop, take two minutes to answer these questions in your Chapter 10 challenge issue. There are no wrong answers -- this is for you. + +1. Which chapter felt the most natural to you? Which one do you want to revisit? +2. Can you explain what a pull request does to someone who has never used GitHub? +3. If you saw a merge conflict right now, would you know where to start? +4. What is one thing you want to try on GitHub this week that you did not get to today? + +> **Screen reader tip:** You can copy these questions into your challenge issue comment and type your answers directly below each one. Use a blank line between each question-answer pair so the structure is clear when read back. + +### Your Challenge Progress + +Look at how many challenge issues you completed today. Each one represents a skill you did not just read about -- you practiced it, posted evidence, and moved on. Some workshops hand you a certificate for sitting in a chair. This one asked you to prove your skills in a live repository, and you did. + +If you completed all eleven challenges, you are ready for Day 2 with a strong foundation. If you missed a few, that is fine -- you can finish them at your own pace before Day 2 begins. The Learning Room stays open. + +### Learning Cards: What You Accomplished Today + +
    +Screen reader users + +- You navigated GitHub entirely by keyboard: headings (`H`), landmarks (`D`), buttons (`B`), links (`K`), and form fields (`F` or `E`) became your primary navigation tools +- You created issues, opened PRs, resolved conflicts, and managed notifications -- all skills that transfer to any repository on GitHub +- Revisit any chapter by pressing `Ctrl+L` in your browser and typing the URL, or by navigating to the docs folder in the Learning Room repository + +
    + +
    +Low vision users + +- Everything you did today at your current zoom level and contrast settings will work the same way tomorrow; GitHub's layout adapts consistently to browser zoom up to 400% +- If you found certain pages hard to read, revisit Settings, Accessibility on GitHub to try a different theme or motion preference before Day 2 +- Your profile page at github.com/your-username now shows contribution activity from today; zoom in on the contribution graph to see your green squares + +
    + +
    +Sighted users + +- Your GitHub profile now shows contribution activity from today: issues created, PRs opened, and commits made appear as green squares on your contribution graph +- Every skill from today (issues, PRs, reviews, labels, notifications) is used daily by professional developers; you practiced the real workflow, not a simplified version +- Bookmark your Learning Room repository and the notifications page (github.com/notifications) for quick access on Day 2 + +
    + + +## What Day 2 Adds + +> **See also:** [Chapter 11: VS Code Interface](11-vscode-interface.md) is where Day 2 begins -- have VS Code installed and ready. + +On Day 1, you worked entirely on GitHub.com. Everything happened in your browser -- creating issues, editing files, opening pull requests, resolving conflicts. On Day 2, you bring that same workflow to your own computer and add powerful new tools on top of it. + +Here is what Day 2 covers: + +| Chapters | Topic | What You Will Do | +|---|---|---| +| [Ch 11](11-vscode-interface.md) -- [Ch 12](12-vscode-accessibility.md) | VS Code deep dive | Install and configure VS Code with full screen reader and accessibility support | +| [Ch 13](13-how-git-works.md) -- [Ch 14](14-git-in-practice.md) | Local Git | Clone repositories, commit locally, push and pull changes between your computer and GitHub | +| [Ch 15](15-code-review.md) | Code review | Review pull requests with inline comments, suggestions, and approval workflows | +| [Ch 16](16-github-copilot.md) | GitHub Copilot | Use AI-assisted coding with accessibility-first prompting techniques | +| [Ch 17](17-issue-templates.md) | Issue templates | Create structured templates so every issue in your project starts with the right information | +| [Ch 18](18-fork-and-contribute.md) | Fork workflow | Fork a repository, make changes, and submit a pull request back to the original project | +| [Ch 19](19-accessibility-agents.md) | Accessibility agents | Build and use custom agents that automate accessibility checks and team workflows | +| [Ch 20](20-build-your-agent.md) | Capstone | Design, build, test, and ship your own accessibility agent from scratch | + +The mental model shift is straightforward: Day 1 taught you *what* GitHub does. Day 2 teaches you how to use it from your own development environment, with real tools that professional developers use every day. + +### Between Days + +If your workshop has a gap between Day 1 and Day 2, here are three optional things you can do to stay sharp: + +1. **Explore your notification settings.** Now that you understand how notifications work, visit [github.com/settings/notifications](https://github.com/settings/notifications) and customize your email and web preferences. There is no wrong configuration -- just find what feels manageable. + +2. **Read issues in a project you care about.** Pick any open source project on GitHub and browse its issue tracker. You now know enough to understand labels, milestones, and comment threads. Notice how maintainers communicate -- you will recognize the patterns from [Chapter 08](08-open-source-culture.md). + +3. **Try a GitHub Skills course.** [GitHub Skills](https://skills.github.com/) offers free, self-paced courses that run inside real repositories. "Introduction to GitHub" is a good one if you want to reinforce what you learned today. See [Appendix Z](appendix-z-github-skills.md) for the full list of recommended courses. + +> **Screen reader tip:** GitHub Skills courses use bot-driven feedback inside pull requests. The interaction model is similar to the Learning Room -- you push a change, a bot reviews it, and you get instructions for the next step. If you completed today's challenges, you already know the workflow. + +### You Already Know More Than You Think + +Think about where you started this morning. You may not have known what a repository was, or how to navigate one with a keyboard, or what happens when two people edit the same file. Now you do. You have created real issues, opened real pull requests, resolved real conflicts, and configured your own notification workflow -- all in a live, shared codebase. + +Day 2 builds on every one of those skills. Nothing gets thrown away. Everything you did today is the foundation for everything that comes next. + + +> **End of Day 1:** Congratulations. You have completed **Challenge 9: Merge Day** and finished the browser-based foundation. [Return to the Course Guide](course-guide.md) to prepare for Day 2. + +--- + + +*Next: [Chapter 11: VS Code Interface](11-vscode-interface.md)* +*Back: [Chapter 09: Labels, Milestones, and Projects](09-labels-milestones-projects.md)* +*Related appendices: [Appendix T: Community and Social](appendix-t-community-and-social.md) | [Appendix U: Discussions and Gists](appendix-u-discussions-and-gists.md)* + diff --git a/admin/qa-bundle/docs/11-vscode-interface.md b/admin/qa-bundle/docs/11-vscode-interface.md new file mode 100644 index 0000000..fb0be2f --- /dev/null +++ b/admin/qa-bundle/docs/11-vscode-interface.md @@ -0,0 +1,1079 @@ +# VS Code: Interface and Setup + +> **Listen to Episode 11:** [VS Code Setup and Accessibility](../admin/PODCASTS.md) - a conversational audio overview covering both this chapter and [Chapter 12](12-vscode-accessibility.md). + +> **Related appendices:** [Appendix G: VS Code Reference](appendix-g-vscode-reference.md) | [Appendix B: Screen Reader Cheat Sheet](appendix-b-screen-reader-cheatsheet.md) +> **Authoritative sources:** [VS Code Docs: User Interface](https://code.visualstudio.com/docs/getstarted/userinterface) | [VS Code Docs: Accessibility](https://code.visualstudio.com/docs/editor/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](12-vscode-accessibility.md). +> +> **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 + +1. **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. + +1. Open your Learning Room repository on GitHub.com. +2. 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. +3. 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`. +4. Open the **Explorer** panel with `Ctrl+Shift+E` (Mac: `Cmd+Shift+E`). Your screen reader should announce the file tree. +5. Navigate to and open `README.md` from the file tree. Use arrow keys to move through files and `Enter` to open. +6. 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. +7. 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. +8. 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. +9. 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: + +```text +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 + +1. 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. +2. Screen reader mode toggle did not announce anything? Open Command Palette (`Ctrl+Shift+P`) and type `Screen Reader` to find the toggle manually. +3. Explorer panel is empty? VS Code may still be loading the repository. Wait 5-10 seconds and press `Ctrl+Shift+E` again. +4. On Mac with VoiceOver, navigation feels wrong? Run `Toggle Screen Reader Accessibility Mode` from Command Palette. VoiceOver sometimes needs the explicit toggle. +5. Cannot find the Accounts button? Open Command Palette and type `Accounts` to manage sign-in from there. +6. Copilot not showing in the status bar? github.dev does not support Copilot - you need desktop VS Code or a Codespace. +7. Shortcut not working? Use Command Palette as a fallback for any action - type what you want to do and VS Code will find the command. +8. Ask facilitator for a side-by-side demo and repeat the same steps. + +### Learning Moment + +Tool setup is part of contribution skill. A stable, accessible editor reduces stress and increases contribution quality. The surfaces you just tested - github.dev launch, screen reader mode, GitHub sign-in, Copilot status, Explorer, Outline, and Command Palette - are the foundation for everything in Day 2. + +### Learning Pattern Used in This Chapter + +1. Open the tool in the simplest way possible (`.` key for github.dev). +2. Sign in and verify your identity and tools are ready (Accounts, Copilot). +3. Configure accessibility before doing any work (screen reader mode first). +4. Verify each navigation surface works with your assistive technology. +5. Record what worked and what didn't (evidence comment). + + +## Table of Contents + +1. [Why VS Code for Open Source Contribution](#1-why-vs-code-for-open-source-contribution) +2. [The Bridge: github.dev - VS Code in Your Browser](#2-the-bridge-githubdev---vs-code-in-your-browser) +3. [Screen Reader Mode in VS Code](#3-screen-reader-mode-in-vs-code) +4. [The VS Code Interface Tour](#4-the-vs-code-interface-tour) +5. [The Accounts Button and GitHub Sign-In](#5-the-accounts-button-and-github-sign-in) +6. [Verifying GitHub Copilot Status](#6-verifying-github-copilot-status) +7. [The Status Bar](#7-the-status-bar) +8. [The Menu Bar](#8-the-menu-bar) +9. [Settings Sync](#9-settings-sync) + - [Profiles](#profiles) +10. [The Settings Editor](#10-the-settings-editor) +11. [The Keyboard Shortcuts Editor](#11-the-keyboard-shortcuts-editor) +12. [Essential Keyboard Navigation and Find/Filter](#12-essential-keyboard-navigation-and-findfilter) +13. [The Problems Panel](#13-the-problems-panel) +14. [The Terminal](#14-the-terminal) +15. [Copilot Chat Window](#15-copilot-chat-window) +16. [Accessible Help, Accessible View, and Accessible Diff](#16-accessible-help-accessible-view-and-accessible-diff) +17. [Accessibility Signals](#17-accessibility-signals) +18. [VS Code Speech - Voice Input and Output](#18-vs-code-speech---voice-input-and-output) +19. [Git Operations Inside VS Code](#19-git-operations-inside-vs-code) + + +--- + +## 1. Why VS Code for Open Source Contribution + +GitHub's browser interface is excellent for reviewing, discussing, and triaging. VS Code is where you create. The difference: + +| Task | Browser | VS Code | +| --- | --- | --- | +| Navigate a repository | Excellent | Explorer sidebar | +| Read issues and PRs | Excellent | GitHub PR extension | +| Comment on a PR | Excellent | GitHub PR extension | +| Edit a file | Web editor | Full text editor with Copilot | +| Review a diff | Files Changed tab | Three-way merge view with navigation | +| Get AI help while writing | Not available | Copilot inline + Chat | +| Run Accessibility Agents | Not available | Copilot Chat with agent files | +| See errors in your contribution | After push | Real-time as you type | + +For Markdown contributions (which is most of what [accessibility-agents](https://github.com/Community-Access/accessibility-agents) needs), VS Code gives you Copilot assistance, live preview, and the same Git workflow - with less tab switching and with agents available on every file you open. + +### Learning Cards: Why VS Code + +
    +Screen reader users + +- VS Code announces errors, warnings, and suggestions via ARIA live regions -- you hear problems as you type instead of after pushing to GitHub +- Press `Ctrl+Shift+P` (Mac: `Cmd+Shift+P`) to open the Command Palette and access every VS Code feature without a mouse +- The Explorer sidebar (`Ctrl+Shift+E`) gives you the same file tree as GitHub.com but with keyboard-driven editing one `Enter` away + +
    + +
    +Low vision users + +- VS Code supports zoom levels up to 500%: press `Ctrl+=` (Mac: `Cmd+=`) to increase and `Ctrl+-` (Mac: `Cmd+-`) to decrease +- High Contrast themes are built in -- open Command Palette and type "Color Theme" to switch +- Inline error squiggles use both color and underline style so they remain visible at any zoom level or contrast setting + +
    + +
    +Sighted users + +- The Activity Bar on the left shows icons for Explorer, Search, Source Control, Extensions, and more -- each lights up when active +- Real-time red/yellow squiggles under errors and warnings appear as you type, replacing the GitHub "push and wait" cycle +- Copilot suggestions appear as dimmed ghost text to the right of your cursor + +
    + + +--- + +## 2. The Bridge: github.dev - VS Code in Your Browser + +### Before you install anything: try VS Code right now in your browser + +GitHub provides a web-based version of VS Code called **github.dev**. It runs entirely in your browser with zero installation. The keyboard shortcuts, screen reader mode, and editor experience are identical to the desktop app. + +### How to Access github.dev + +#### Method 1: The Period Key Shortcut (Fastest) + +From any GitHub repository page: + +1. Press `.` (period key - just the period, no modifier keys) +2. The page transforms into VS Code +3. You are now editing in github.dev +4. The URL changes to `github.dev/owner/repo` +5. Screen reader mode works exactly as it does in desktop VS Code (toggle with `Shift+Alt+F1`) + +#### Where it works + +- Repository home pages +- File view pages +- Pull request pages +- Any branch or commit view + +**Screen reader note:** The period key shortcut is a single keypress - no modifier keys. It is GitHub's universal "open this in VS Code" command. + +**Alternative: Press `>` (Shift+Period)** to open github.dev in a **new tab**. This preserves your GitHub page and is the preferred method when you want to keep both interfaces open. + +#### Method 2: Direct URL + +Change the domain in any GitHub URL: + +- `github.com/owner/repo` becomes `github.dev/owner/repo` +- Works for any branch, file, or commit URL + +#### Method 3: From the Repository Page + +
    +Visual / mouse users + +1. Click the green **Code** button on any repository page +2. In the dropdown, click **Open with github.dev** + +
    + +
    +Screen reader users (NVDA / JAWS / VoiceOver) + +1. Navigate to the Code button (press `B` or `Tab` until you hear "Code, button" or similar) +2. Press `Enter` to open the dropdown menu +3. Press `Down Arrow` to reach "Open with github.dev" +4. Press `Enter` + +
    + + +### What You Get in github.dev + +Everything in the list below works **exactly like desktop VS Code**: + +- **Full text editor with syntax highlighting** +- **All VS Code keyboard shortcuts** (see [Section 11: Keyboard Shortcuts Editor](#11-the-keyboard-shortcuts-editor) and [Appendix M](appendix-g-vscode-reference.md#5-complete-keyboard-shortcuts)) +- **Screen reader mode** (`Shift+Alt+F1` to activate - Mac: `Shift+Option+F1`) +- **File Explorer** (`Ctrl+Shift+E` - Mac: `Cmd+Shift+E`) - browse the entire repository +- **Search across files** (`Ctrl+Shift+F` - Mac: `Cmd+Shift+F`) +- **Source Control (Git)** (`Ctrl+Shift+G` - Mac: `Cmd+Shift+G`) - stage, commit, push changes +- **Markdown preview** (`Ctrl+Shift+V` - Mac: `Cmd+Shift+V`) +- **Command Palette** (`Ctrl+Shift+P` - Mac: `Cmd+Shift+P`) - access every VS Code command +- **Go to File** (`Ctrl+P` - Mac: `Cmd+P`) - instant file picker +- **Go to Symbol** (`Ctrl+Shift+O` - Mac: `Cmd+Shift+O`) - navigate by headings in Markdown +- **Multiple editor tabs and split view** +- **Settings sync** - if you sign in, your VS Code settings apply here too + + +### What github.dev Does NOT Have + +- **No terminal** - cannot run shell commands, npm, git CLI +- **No GitHub Copilot** - Copilot requires the desktop app or a Codespace +- **No Accessibility Agents** - agents rely on extensions that need desktop VS Code +- **No extension installation** - extensions are disabled in github.dev +- **No debugger** - debugging requires a local environment +- **No live server or preview** - except Markdown preview, which does work + +These limitations are why **desktop VS Code exists**. github.dev is for quick edits and reading code. Desktop is for Copilot, agents, terminal workflows, and full development. + + +### Why github.dev Matters for This Workshop + +**It is the bridge.** You spend Day 1 in the GitHub browser interface. You spend Day 2 in desktop VS Code. github.dev sits in between: + +- Same keyboard shortcuts as desktop VS Code (you learn them once) +- Same screen reader mode (you configure it once) +- Same file navigation patterns (Explorer, `Ctrl+P` / Mac: `Cmd+P`, `Ctrl+Shift+O` / Mac: `Cmd+Shift+O`) +- But accessible instantly from any GitHub page with one keystroke + +#### Use github.dev when + +- You want to edit a file quickly without switching apps +- You are on a machine where you cannot install software +- You want to browse code with VS Code navigation (symbols, search, split view) +- You are reviewing a PR and want to see the full file context + +#### Use desktop VS Code when + +- You need Copilot inline suggestions +- You want to run Accessibility Agents +- You are making multi-file changes that benefit from AI assistance +- You need a terminal for git commands or running scripts + + +### Screen Reader Experience in github.dev + +#### Activate screen reader mode immediately + +1. Press `.` on any GitHub repository to open github.dev +2. Press `Shift+Alt+F1` (Mac: `Shift+Option+F1`) to enable screen reader mode +3. VS Code announces "Screen reader optimized" + +#### What changes + +- Focus behavior adjusts for keyboard navigation +- Code suggestions are announced via ARIA live regions +- Error messages are announced when you navigate to them +- Inline decorations are suppressed to reduce noise + +#### Navigation + +- Use `Ctrl+Shift+E` to open the Explorer (file tree) +- Use `Up/Down Arrow` to navigate files +- Press `Enter` on a file to open it in the editor +- The editor behaves like a standard text area - your screen reader's reading commands work normally + +#### NVDA/JAWS users + +- You remain in Browse/Virtual mode for the overall interface +- When focus enters the editor text area, you are automatically in Forms/Focus mode +- All standard cursor movement works: `Home`, `End`, `Ctrl+Home`, `Ctrl+End`, `Ctrl+F` to find + +#### VoiceOver users + +- Quick Nav OFF when inside the editor (`Left Arrow + Right Arrow` to toggle) +- Use `VO+Shift+Down` to interact with the editor area +- Standard text navigation (`Control+A` for line start, `Control+E` for line end, etc.) + +### Learning Cards: github.dev + +
    +Screen reader users + +- Press `.` (period, no modifiers) on any GitHub repository page to open github.dev instantly -- your screen reader announces the VS Code interface loading +- Immediately press `Shift+Alt+F1` (Mac: `Shift+Option+F1`) to enable screen reader mode after github.dev loads +- Use `Ctrl+Shift+O` (Mac: `Cmd+Shift+O`) to navigate by headings in Markdown files -- this is the fastest way to scan a document + +
    + +
    +Low vision users + +- github.dev inherits your browser zoom level -- use `Ctrl+=` (Mac: `Cmd+=`) to enlarge the entire editor before you start working +- Switch to a High Contrast theme via Command Palette (`Ctrl+Shift+P` then type "Color Theme") -- this persists for the session +- The minimap on the right edge of the editor shows a zoomed-out preview of your file; disable it in Settings if it is distracting at high zoom + +
    + +
    +Sighted users + +- Look for the URL changing from `github.com` to `github.dev` to confirm you are in the web editor +- The Activity Bar on the left and the Status Bar at the bottom look identical to desktop VS Code +- Use `Ctrl+P` (Mac: `Cmd+P`) to open the quick file picker -- start typing a filename and select from the dropdown + +
    + + +### Try It Right Now + +Before reading the rest of this guide: + +1. Open your Learning Room repository in your browser +2. Press `.` (period key) +3. github.dev opens +4. Press `Shift+Alt+F1` (Mac: `Shift+Option+F1`) to enable screen reader mode +5. Press `Ctrl+Shift+E` (Mac: `Cmd+Shift+E`) to open the Explorer +6. Navigate to `README.md` and press `Enter` +7. Press `Ctrl+Home` (Mac: `Cmd+Up`) to go to the top of the file +8. Press `Ctrl+Shift+O` (Mac: `Cmd+Shift+O`) to see the outline (all headings) +9. Close the tab when done + +**You just used VS Code.** The desktop version in the rest of this guide is the same experience - with Copilot, agents, and a terminal added. + + +--- + +## 3. Screen Reader Mode in VS Code + +> **See also:** [Chapter 12: VS Code Accessibility](12-vscode-accessibility.md) goes deeper into accessibility features, Accessible View, and signal customization. + +> **Who needs this section?** If you use NVDA, JAWS, VoiceOver, or another screen reader, read this section before continuing. If you are not using a screen reader, you can skip to [Section 4](#4-the-vs-code-interface-tour) - VS Code works fully without enabling this mode. + +VS Code has built-in accessibility support designed for screen reader users. It changes how focus moves, how announcements work, and how navigation behaves. + +### Activating Screen Reader Mode + +| Method | Steps | +| --- | --- | +| Keyboard shortcut | `Shift+Alt+F1` (Windows) / `Shift+Option+F1` (Mac) | +| Command Palette | `Ctrl+Shift+P` (Windows) / `Cmd+Shift+P` (Mac) then type "screen reader" then select "Toggle Screen Reader Accessibility Mode" | +| Auto-detection | VS Code detects NVDA and JAWS automatically on Windows; VoiceOver on macOS | + +#### Verify it is active + +Open Settings (`Ctrl+,` - Mac: `Cmd+,`) then search for `accessibility support` then confirm it shows `on` (not `auto`). + +### What Changes in Screen Reader Mode + +| Area | Normal Mode | Screen Reader Mode | +| --- | --- | --- | +| Suggestions list | Popup overlay | Announced via ARIA live region | +| Diff navigation | Visual highlighting | Announces "Added" / "Removed" before line content | +| Error indicators | Red underlines | Announced on focus | +| Inline decorations | Displayed visually | Suppressed to reduce noise | +| Tab completion | Visual ghost text | Announced as suggestion | + +### NVDA-Specific Settings for VS Code + +VS Code uses a web-based renderer. Configure NVDA for best results: + +1. Open NVDA Menu then Preferences then Settings then Browse Mode +2. Set "Maximum length of text on a single line" to `10000` (prevents truncation in long lines) +3. Under Object Presentation: set "Report tooltip delay" to `off` +4. Recommended: use **NVDA + Google Chrome** for the integrated browser panels + +### JAWS-Specific Settings for VS Code + +1. JAWS should detect VS Code automatically and switch to PC Cursor mode for the editor +2. If the editor feels unresponsive, press `Insert+Z` to toggle virtual cursor off +3. For the integrated terminal: use `Insert+Z` to enter forms/PC mode, then interact with the terminal + +### VoiceOver-Specific Settings for VS Code (macOS) + +1. Open VS Code then `Shift+Alt+F1` (Mac: `Shift+Option+F1`) to confirm screen reader mode +2. In VoiceOver Utility: Verbosity then set "Punctuation" to "All" for reading code +3. Use Quick Nav OFF (`Left+Right Arrow`) when inside the editor - standard cursor navigation is more predictable +4. Use `VO+Shift+Down` to interact with the editor, `VO+Shift+Up` to stop interacting + +### Learning Cards: Screen Reader Mode + +
    +Screen reader users + +- Toggle screen reader mode with `Shift+Alt+F1` (Mac: `Shift+Option+F1`) -- VS Code announces "Screen reader optimized" when activated +- Set `editor.accessibilitySupport` to `"on"` (not `"auto"`) in Settings (`Ctrl+,`) for consistent behavior across sessions +- NVDA users: set "Maximum length of text on a single line" to 10000 in Browse Mode settings to prevent long code lines from being truncated + +
    + +
    +Low vision users + +- Screen reader mode suppresses inline decorations that can clutter the display -- enable it even if you use a magnifier for a cleaner view +- Pair screen reader mode with a High Contrast theme (`Ctrl+Shift+P` then "Color Theme") for maximum readability +- Use `Ctrl+=` / `Ctrl+-` (Mac: `Cmd+=` / `Cmd+-`) to adjust font size independently of your OS zoom settings + +
    + +
    +Sighted users + +- Screen reader mode is invisible to sighted users -- you will not notice any visual changes if you toggle it on +- If you are pair-programming with a screen reader user, enable it so the experience is consistent for both of you +- The mode changes how suggestions are announced but does not remove any visual features you rely on + +
    + + +--- + +## 4. 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 + +```text ++----------------------------------------------------------+ +| 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. + +### Navigating Between Regions + +| Region | Keyboard Shortcut | What You Hear (Screen Reader) | +| --- | --- | --- | +| Activity Bar icons | `Ctrl+Shift+E` / `G` / `F` / `X` / etc. | "Explorer", "Source Control", etc. | +| Sidebar content | Follows activity bar selection | Tree view or list content | +| Editor area | `Ctrl+1` (first editor group) | File name and cursor position | +| Panel | `Ctrl+Backtick` (terminal) or `Ctrl+Shift+M` (problems) | Panel name announcement | +| Status Bar | `F6` cycles through regions | Status bar items read left to right | + +**Key insight:** Press `F6` repeatedly to cycle focus through the major regions: Sidebar, Editor, Panel, Status Bar, and back. This is the universal "where am I, take me somewhere else" key in VS Code. + +### Learning Cards: Finding Your Way Around VS Code + +
    +Screen reader users (NVDA / JAWS / VoiceOver) + +- **F6** is your best friend - it cycles through regions and your screen reader announces each one +- **Ctrl+Shift+P** (Command Palette) is your safety net - type any action name and VS Code finds it +- **Alt+H** (Accessible Help) tells you what shortcuts work in your current context +- Use **Ctrl+Shift+E** for Explorer, **Ctrl+Shift+G** for Source Control, **Ctrl+Shift+F** for Search +- The editor text area acts like a standard text field - all your screen reader reading commands work + +
    + +
    +Low vision users + +- **Ctrl+=** / **Ctrl+-** to zoom the entire VS Code window (all UI elements scale) +- **Ctrl+,** then search `editor.fontSize` to set a comfortable default editor font size +- **Ctrl+,** then search `window.zoomLevel` to set a persistent zoom level +- High Contrast themes: **Ctrl+K Ctrl+T** then choose "High Contrast" or "High Contrast Light" +- **Ctrl+,** then search `minimap` - set `editor.minimap.enabled` to `false` to remove the small code overview that may be hard to see +- **Ctrl+B** toggles the sidebar to give the editor more space + +
    + +
    +Sighted users + +- Click icons in the Activity Bar (left edge) to switch sidebar views +- The bottom Panel shows Terminal, Problems, Output, and Debug Console +- Drag panel borders to resize regions or double-click to collapse them +- **Ctrl+B** toggles the sidebar for a wider editor area +- **Ctrl+J** toggles the bottom Panel +- **Ctrl+Shift+P** opens the Command Palette - the universal search for any action + +
    + + +--- + +## 5. The Accounts Button and GitHub Sign-In + +> **See also:** [Chapter 14: Git in Practice](14-git-in-practice.md) covers the full Git workflow in VS Code including the Source Control panel. + +The **Accounts** button sits at the bottom of the Activity Bar (the vertical icon strip on the left side of VS Code). It manages your authentication with GitHub, Microsoft, and other services. + +### Why Sign In Matters + +- **GitHub Copilot** requires an active GitHub sign-in to function +- **Settings Sync** requires sign-in to synchronize your preferences across machines +- **GitHub Pull Requests extension** needs authentication to create and review PRs from VS Code +- Your GitHub identity appears in commits you make from VS Code + +### Signing In + +#### From the Accounts Button + +1. Press `F6` until you hear the Activity Bar, then arrow down to the **Accounts** button (it is at the very bottom of the bar) +2. Press `Enter` to open the Accounts menu +3. Select **"Sign in with GitHub to use GitHub Copilot"** (or a similar prompt) +4. A browser window opens for GitHub OAuth authorization +5. Authorize VS Code, then return to the editor +6. Your screen reader announces your GitHub username in the Accounts button + +#### From the Command Palette + +1. Press `Ctrl+Shift+P` then type `sign in` +2. Select **"GitHub: Sign In"** +3. Complete the browser OAuth flow and return to VS Code + +### Verifying You Are Signed In + +- **Accounts button:** Press `F6` to reach the Activity Bar, arrow down to Accounts. A screen reader announces your username. +- **Command Palette:** `Ctrl+Shift+P` then type `GitHub Copilot: Status`. If Copilot shows ready, you are signed in. +- **Status Bar:** Look for (or hear) the Copilot icon in the status bar at the bottom of the window. + +### Learning Cards: GitHub Sign-In + +
    +Screen reader users + +- Press `F6` to cycle to the Activity Bar, then `Down Arrow` to the bottom to find the Accounts button +- After signing in, the Accounts button label changes from "Accounts" to your GitHub username +- If browser OAuth does not redirect back automatically, check for a "paste this code" dialog in VS Code - type the code displayed in your browser + +
    + +
    +Low vision users + +- The Accounts icon is the person silhouette at the bottom of the leftmost icon column +- After sign-in, a small dot or badge appears on the icon indicating active session +- If the icon is hard to see, use **Ctrl+Shift+P** and type `Accounts` to manage sign-in from the Command Palette + +
    + +
    +Sighted users + +- Click the person icon at the bottom of the Activity Bar +- A dropdown menu shows your sign-in status and available accounts +- After sign-in, the icon changes to show your GitHub avatar + +
    + + +--- + +## 6. Verifying GitHub Copilot Status + +GitHub Copilot is your AI pair programmer. Before starting any contribution work, confirm it is active and responding. + +### Where to Check Copilot Status + +#### Status Bar Indicator + +The Copilot icon appears in the **Status Bar** at the bottom-right of the VS Code window. + +| Icon State | Meaning | +| --- | --- | +| Copilot icon (normal) | Copilot is active and ready | +| Copilot icon with warning triangle | Copilot has a configuration issue | +| Copilot icon with slash-through | Copilot is disabled for this file type | +| No Copilot icon | Extension not installed or not signed in | + +#### Command Palette Check + +1. Press `Ctrl+Shift+P` +2. Type `GitHub Copilot: Status` +3. The output shows whether Copilot is signed in, active, or has errors + +#### Quick Test + +1. Open any `.md` file in the editor +2. Start typing a sentence (for example, `## Getting Started with`) +3. If Copilot is active, a gray ghost-text suggestion appears after a brief pause +4. Press `Tab` to accept or `Escape` to dismiss + +### Troubleshooting Copilot + +| Problem | Solution | +| --- | --- | +| No Copilot icon in status bar | On VS Code 1.116+, Copilot is built-in -- sign in to GitHub (`Ctrl+Shift+P` then `GitHub: Sign in`). On older VS Code: `Ctrl+Shift+X` then search `GitHub Copilot` then install | +| Icon shows warning | Open Output panel (`Ctrl+Shift+U`), select "GitHub Copilot" from the dropdown, read the error | +| "Not signed in" | Sign in to GitHub (Section 5 above) | +| Copilot not suggesting | Check that Copilot is not disabled for the file type: `Ctrl+Shift+P` then `GitHub Copilot: Toggle` | +| Works on desktop but not github.dev | Expected behavior. github.dev does not support Copilot. Use desktop VS Code or a Codespace. | + +### Learning Cards: Copilot Status + +
    +Screen reader users + +- The Copilot status bar item is announced when you Tab through the status bar +- After sign-in, press `Ctrl+Shift+P` then type `Copilot Status` - the announcement tells you the full state +- When Copilot generates a suggestion, NVDA and JAWS announce it as ghost text; press `Tab` to accept +- Press `Alt+F2` (Accessible View) to read the full Copilot suggestion in a clean text view + +
    + +
    +Low vision users + +- The Copilot icon is a small two-petal/sparkle icon near the right side of the Status Bar +- Copilot suggestions appear as dimmed gray text ahead of your cursor - increase editor contrast or zoom level if they are hard to see +- Use a High Contrast theme for clearer distinction between your text and Copilot ghost text + +
    + +
    +Sighted users + +- Look for the Copilot sparkle icon in the bottom-right Status Bar +- Gray ghost text after your cursor means Copilot is generating a suggestion +- Click the Copilot icon for a quick status menu showing enabled/disabled state + +
    + + +--- + +## 7. The Status Bar + +The **Status Bar** is the thin strip at the bottom of the VS Code window. It provides real-time information about your workspace, file, and active tools. + +### What the Status Bar Contains (Left to Right) + +| Item | What It Shows | How to Interact | +| --- | --- | --- | +| Git branch | Current branch name (e.g., `main`) | Click or press to switch branches | +| Sync status | Pending push/pull count | Click to sync (push/pull) | +| Errors and warnings | Error/warning count in workspace | Click opens Problems panel (`Ctrl+Shift+M`) | +| Line and column | Cursor position (e.g., `Ln 42, Col 8`) | Click opens Go to Line (`Ctrl+G`) | +| Indentation | Spaces or tabs and count | Click to change indent settings | +| Encoding | File encoding (e.g., `UTF-8`) | Click to change encoding | +| End of line | `LF` or `CRLF` | Click to change line endings | +| Language mode | File type (e.g., `Markdown`) | Click to change language | +| Copilot status | GitHub Copilot state | Click for Copilot menu | +| Notification bell | Unread notifications | Click to view notifications | + +### Navigating the Status Bar with a Keyboard + +1. Press `F6` until your screen reader announces the Status Bar +2. Use `Tab` to move between items from left to right +3. Press `Enter` on any item to activate it (open a picker, toggle a setting, etc.) +4. Press `Escape` to return to the editor + +### Learning Cards: Status Bar + +
    +Screen reader users + +- Press `F6` repeatedly until you hear "Status Bar" - then `Tab` through items +- Each item is announced with its current value (e.g., "Ln 42, Col 8" or "main branch") +- The errors/warnings item announces the count - press `Enter` to jump to the Problems panel +- After reviewing, press `Escape` then `Ctrl+1` to return to the editor + +
    + +
    +Low vision users + +- The Status Bar text is small by default - use `Ctrl+=` to zoom the entire window +- Different-colored sections help identify areas: left side (Git/sync), center (position), right side (Copilot/language) +- Status Bar background color changes in certain contexts (e.g., debugging turns it orange, no folder is purple) + +
    + +
    +Sighted users + +- Click any Status Bar item to interact with it +- The colored background indicates context: blue (normal workspace), purple (no folder open), orange (debugging) +- Hover over items for tooltips with additional detail + +
    + + +--- + +## 8. The Menu Bar + +The **Menu Bar** runs along the top of the VS Code window and provides structured access to every command category. + +### Menu Bar Structure + +| Menu | Key Contents | +| --- | --- | +| **File** | New File, Open Folder, Save, Auto Save, Preferences (Settings, Keyboard Shortcuts, Extensions) | +| **Edit** | Undo, Redo, Cut, Copy, Paste, Find, Replace | +| **Selection** | Select All, Expand Selection, Add Cursor | +| **View** | Explorer, Search, Source Control, Extensions, Terminal, Problems, Command Palette, Appearance (zoom, sidebar, panel toggles) | +| **Go** | Go to File, Go to Symbol, Go to Line, Go to Definition, Back/Forward navigation | +| **Run** | Start Debugging, Run Without Debugging, Add Configuration | +| **Terminal** | New Terminal, Split Terminal, Run Active File, Run Selected Text | +| **Help** | Welcome, Documentation, Keyboard Shortcuts Reference, Accessibility Help | + +### Accessing the Menu Bar + +| Method | Steps | +| --- | --- | +| Keyboard (Windows/Linux) | Press `Alt` or `F10` to focus the menu bar, then use arrow keys | +| Keyboard (Mac) | `Ctrl+F2` or use the system menu bar | +| Command Palette | `Ctrl+Shift+P` gives access to all the same commands without the menu | + +### Learning Cards: Menu Bar + +
    +Screen reader users + +- Press `F10` (or `Alt`) to enter the Menu Bar. Your screen reader announces "File" menu +- Use `Left/Right Arrow` to move between menus (File, Edit, View, Go, Run, Terminal, Help) +- Press `Enter` or `Down Arrow` to open a menu and browse items +- Each menu item includes its keyboard shortcut in the announcement (e.g., "New File, Ctrl+N") +- Press `Escape` to close and return to the editor + +
    + +
    +Low vision users + +- The Menu Bar respects your zoom level - increase window zoom for larger text +- Menu items show keyboard shortcuts on the right side of each entry +- Use the Help menu to access "Keyboard Shortcuts Reference" for a printable cheat sheet + +
    + +
    +Sighted users + +- Click any menu name to open its dropdown +- Keyboard shortcuts are displayed to the right of each menu item +- The View menu controls which panels and sidebars are visible + +
    + + +--- + +## 9. Settings Sync + +**Settings Sync** synchronizes your VS Code configuration across multiple machines and between desktop VS Code and github.dev. When you sign in and enable sync, your settings, keyboard shortcuts, extensions, UI state, and profiles travel with you. + +### What Gets Synced + +| Category | Examples | +| --- | --- | +| Settings | `editor.fontSize`, `editor.accessibilitySupport`, color theme, zoom level | +| Keyboard Shortcuts | All custom keybindings | +| Extensions | Installed extensions list | +| UI State | Sidebar position, panel visibility, recent files | +| Profiles | Named collections of settings for different workflows | + +### Enabling Settings Sync + +1. Open the **Accounts** button (Activity Bar, bottom-left) or press `Ctrl+Shift+P` then type `Settings Sync: Turn On` +2. Sign in with your GitHub account (or Microsoft account) +3. Select which categories to sync (recommended: sync everything) +4. VS Code syncs immediately and on every subsequent change + +### Conflict Resolution + +If settings differ between machines, VS Code shows a merge editor where you choose which version to keep. This is similar to a Git merge conflict but for settings. + +### Learning Cards: Settings Sync + +
    +Screen reader users + +- After enabling sync, all your accessibility settings (screen reader mode, accessibility signals, minimap disabled) apply on every machine +- Changes sync automatically in the background - no manual action needed after initial setup +- If a conflict occurs, VS Code opens a merge editor that is navigable with standard diff commands (F7 / Shift+F7) + +
    + +
    +Low vision users + +- Your zoom level, font size, and High Contrast theme sync across machines +- After initial setup on one machine, every other VS Code instance immediately gets the same visual configuration +- Use Profiles to maintain separate configurations (e.g., "Presentation" profile with extra-large fonts) + +
    + +
    +Sighted users + +- The sync status appears as a circular arrow icon in the Activity Bar (bottom-left, near Accounts) +- Conflicts and sync status are shown via notification banners +- Use `Ctrl+Shift+P` then "Settings Sync: Show Synced Data" to review what was synchronized + +
    + +### Profiles + +VS Code **Profiles** let you create named collections of settings, extensions, keyboard shortcuts, snippets, tasks, and UI state. Each profile is independent - switching profiles changes your entire VS Code configuration instantly. This is useful when you work in different contexts (workshop vs. daily development) or need to present with different display settings. + +#### Creating a Profile + +| Method | Steps | +| --- | --- | +| Command Palette | `Ctrl+Shift+P` then type `Profiles: Create Profile` | +| Gear menu | Click the gear icon (bottom-left of Activity Bar) then `Profiles` then `Create Profile` | + +When creating a profile, you choose what to include: + +- **Settings** - editor preferences, accessibility options, theme +- **Keyboard Shortcuts** - all custom keybindings +- **Extensions** - which extensions are installed and enabled +- **Snippets** - code snippet definitions +- **Tasks** - task runner configurations +- **UI State** - sidebar position, panel layout, view visibility + +You can start from the current configuration, an empty profile, or an existing profile template. + +#### Switching Profiles + +| Method | Steps | +| --- | --- | +| Command Palette | `Ctrl+Shift+P` then type `Profiles: Switch Profile` | +| Gear menu | Click the gear icon then `Profiles` then select a profile name | +| Status Bar | The current profile name appears in the Status Bar when you are not using the Default profile - click it to switch | + +The active profile name appears in the VS Code title bar and Status Bar so you always know which configuration is active. + +#### Workshop Profile Recommendations + +Create these profiles before the workshop: + +| Profile Name | Purpose | Key Settings | +| --- | --- | --- | +| **Workshop** | Accessibility-optimized for this event | Screen reader mode on, accessibility signals enabled, minimap off, word wrap on (see the [Recommended Workshop Profile](#recommended-workshop-profile) settings in Section 17) | +| **Presentation** | Large fonts for demos or shared screens | `editor.fontSize: 24`, `terminal.integrated.fontSize: 20`, `window.zoomLevel: 2`, High Contrast theme | +| **Default** | Your everyday development settings | Whatever you normally use | + +#### Exporting and Sharing Profiles + +Profiles can be exported and shared: + +1. `Ctrl+Shift+P` then type `Profiles: Export Profile` +2. Choose what to include (settings, extensions, etc.) +3. Export as a **GitHub gist** (shareable link) or a **local file** +4. Share the link or file with others + +To import: `Ctrl+Shift+P` then `Profiles: Import Profile` and paste the gist URL or select the file. + +**Workshop tip:** Facilitators can export a pre-configured Workshop profile as a GitHub gist and share the link. Students import it in one step and immediately have all accessibility settings configured. + +#### Profiles and Settings Sync + +Profiles sync across machines through Settings Sync. When you create a profile on one machine and have Settings Sync enabled, the profile appears on every other machine where you are signed in. Each profile syncs independently - changes to one profile do not affect others. + +#### Learning Cards: Profiles + +
    +Screen reader users + +- The Command Palette is the fastest way to switch profiles: `Ctrl+Shift+P` then type `Switch Profile` +- Your screen reader announces the profile name when you switch - listen for the confirmation +- Create a **Workshop** profile with `editor.accessibilitySupport: "on"` and all your accessibility signals configured, so you can switch to it instantly at the start of each session +- The Default profile is always available as a fallback + +
    + +
    +Low vision users + +- Create a **Presentation** profile with large fonts, high zoom, and a High Contrast theme for pair programming or demos +- Switching profiles changes everything at once - no need to adjust multiple settings individually +- The current profile name in the title bar confirms which configuration is active + +
    + +
    +Sighted users + +- The gear icon in the Activity Bar (bottom-left) provides quick access to profile management +- Profile names appear in the title bar so you always know your current context +- Export your team's recommended profile as a GitHub gist for easy onboarding + +
    + + +--- + +## 10. The Settings Editor + +The Settings Editor is where you customize VS Code. There are two views: the graphical settings UI and the raw `settings.json` file. + +### Opening the Settings Editor + +| Method | Shortcut | +| --- | --- | +| Graphical Settings UI | `Ctrl+,` (Mac: `Cmd+,`) | +| JSON Settings file | `Ctrl+Shift+P` then type "Open User Settings (JSON)" | + +### Navigating the Settings Editor + +The graphical Settings UI has a **search box** at the top. Type any keyword and the settings list filters instantly. + +#### Special Search Filters + +| Filter | What It Shows | +| --- | --- | +| `@modified` | Only settings you have changed from their defaults | +| `@tag:accessibility` | All accessibility-related settings | +| `@tag:advanced` | Advanced, less commonly used settings | +| `@tag:experimental` | Experimental features not yet enabled by default | +| `@ext:github.copilot` | Settings for the GitHub Copilot extension | + +### Key Accessibility Settings to Configure + +```json +{ + "editor.accessibilitySupport": "on", + "editor.minimap.enabled": false, + "editor.wordWrap": "on", + "editor.renderWhitespace": "none", + "editor.fontSize": 16, + "accessibility.signals.lineHasError": "on", + "accessibility.signals.taskCompleted": "on", + "accessibility.signals.chatResponseReceived": "on" +} +``` + +### Learning Cards: Settings Editor + +
    +Screen reader users + +- Press `Ctrl+,` to open Settings. Focus lands in the search box - start typing immediately +- Type `@tag:accessibility` to see all accessibility settings grouped together +- Each setting is a form control (checkbox, dropdown, or text input) - use standard form navigation +- For direct JSON editing: `Ctrl+Shift+P` then "Open User Settings (JSON)" - this gives you a standard text editor + +
    + +
    +Low vision users + +- Search for `editor.fontSize` to set your preferred font size for the code editor +- Search for `window.zoomLevel` to set the overall window zoom (affects all UI) +- Search for `theme` to switch to High Contrast or High Contrast Light themes +- The gear icon has a checkmark for modified settings, making it easy to spot what you have changed + +
    + +
    +Sighted users + +- Click the gear icon in the bottom-left corner, then select "Settings" +- Use the search box to filter thousands of settings down to what you need +- The "Modified" indicator (blue bar) shows which settings you have customized +- Use the tabs at the top to switch between User settings (global) and Workspace settings (per-project) + +
    + + +--- + +## 11. The Keyboard Shortcuts Editor + +The Keyboard Shortcuts Editor lets you view, search, and customize every keyboard shortcut in VS Code. + +### Opening the Keyboard Shortcuts Editor + +| Method | Shortcut | +| --- | --- | +| Graphical editor | `Ctrl+K Ctrl+S` | +| JSON editor | `Ctrl+Shift+P` then type "Open Keyboard Shortcuts (JSON)" | +| From Menu Bar | File then Preferences then Keyboard Shortcuts | + +### Searching for Shortcuts + +The editor has a search box that supports: + +- **Command name:** Type `toggle terminal` to find the terminal toggle shortcut +- **Keystroke recording:** Click the keyboard icon (or press the record keys button) to record a key combination and find what it does +- **When clause:** Find shortcuts that only apply in specific contexts + +### Customizing a Shortcut + +1. Find the command in the list +2. Double-click the keybinding column (or press `Enter` on the row, then `Enter` again on the keybinding) +3. Press your desired key combination +4. Press `Enter` to confirm + +### Learning Cards: Keyboard Shortcuts Editor + +
    +Screen reader users + +- Press `Ctrl+K Ctrl+S` to open the Keyboard Shortcuts Editor. Focus lands in the search box. +- The results list is a table. Each row announces: Command name, Keybinding, When clause, and Source. +- Navigate rows with `Up/Down Arrow`. Press `Enter` to edit a keybinding. +- Tip: search for `accessibility` to find all accessibility-related shortcuts at once. + +
    + +
    +Low vision users + +- The shortcut editor is a searchable, sortable table - zoom in as needed +- The Source column shows whether a shortcut is from Default, User, or an Extension +- Use the record keys feature to check what any key combination currently does + +
    + +
    +Sighted users + +- Press `Ctrl+K Ctrl+S` to open the visual editor +- Click the keyboard icon in the search bar to record a keystroke and find its binding +- Right-click any row for options to change, remove, or reset a keybinding + +
    + +--- + +*Next: [Chapter 12: VS Code Accessibility](12-vscode-accessibility.md)* +*Back: [Chapter 10: Notifications and Day 1 Close](10-notifications-and-day-1-close.md)* +*Related appendices: [Appendix G: VS Code Reference](appendix-g-vscode-reference.md) | [Appendix B: Screen Reader Cheat Sheet](appendix-b-screen-reader-cheatsheet.md)* + diff --git a/admin/qa-bundle/docs/12-vscode-accessibility.md b/admin/qa-bundle/docs/12-vscode-accessibility.md new file mode 100644 index 0000000..853ec4e --- /dev/null +++ b/admin/qa-bundle/docs/12-vscode-accessibility.md @@ -0,0 +1,1201 @@ +# VS Code: Accessibility Deep Dive + +> **Listen to Episode 11:** [VS Code Setup and Accessibility](../admin/PODCASTS.md) - a conversational audio overview covering both [Chapter 11](11-vscode-interface.md) and this chapter. + +> **Related appendices:** [Appendix G: VS Code Reference](appendix-g-vscode-reference.md) | [Appendix B: Screen Reader Cheat Sheet](appendix-b-screen-reader-cheatsheet.md) +> **Authoritative sources:** [VS Code Docs: Accessibility](https://code.visualstudio.com/docs/editor/accessibility) | [GitHub Accessibility: GitHub Copilot in VS Code](https://accessibility.github.com/documentation/guide/github-copilot-vsc/) + + +## Accessibility Features for Power Users + +> **Challenge 10: Go Local** depends on the accessibility features covered in this chapter. Configure these settings before your first local commit. + +> **Day 2, Block 1 Material (continued)** +> +> This chapter covers the accessibility features that make VS Code productive for screen reader users, keyboard-only users, and low-vision users: essential keyboard navigation, the Problems panel, the Terminal, Copilot Chat, Accessible Help/View/Diff, Accessibility Signals, and VS Code Speech. +> +> For VS Code interface basics (setup, sign-in, Activity Bar, Settings, keyboard shortcuts), see [Chapter 11: VS Code Interface and Setup](11-vscode-interface.md). + +## Table of Contents + +12. [Essential Keyboard Navigation and Find/Filter](#12-essential-keyboard-navigation-and-findfilter) +13. [The Problems Panel](#13-the-problems-panel) +14. [The Terminal](#14-the-terminal) +15. [Copilot Chat Window](#15-copilot-chat-window) +16. [Accessible Help, Accessible View, and Accessible Diff](#16-accessible-help-accessible-view-and-accessible-diff) +17. [Accessibility Signals](#17-accessibility-signals) +18. [VS Code Speech - Voice Input and Output](#18-vs-code-speech---voice-input-and-output) +19. [Markdown Authoring in VS Code](#19-markdown-authoring-in-vs-code) +20. [If You Get Stuck](#if-you-get-stuck) + +## 12. Essential Keyboard Navigation and Find/Filter + +### Panels and Areas + +> **Mac users:** Substitute `Cmd` for `Ctrl` and `Option` for `Alt` in all shortcuts below. + +| Area | Shortcut (Windows) | What Gets Focus | +| --- | --- | --- | +| Explorer (file tree) | `Ctrl+Shift+E` | Folder/file list | +| Search | `Ctrl+Shift+F` | Search input | +| Source Control (Git) | `Ctrl+Shift+G` | Changes list | +| Extensions | `Ctrl+Shift+X` | Extensions list | +| Terminal | `` Ctrl+` `` | Terminal input | +| Copilot Chat | `Ctrl+Shift+I` | Chat input | +| Command Palette | `Ctrl+Shift+P` | Command search input | +| Editor | `Ctrl+1` | Active editor file | +| Problems panel | `Ctrl+Shift+M` | List of all errors and warnings | + +### Within the Editor + +| Action | Shortcut | +| --- | --- | +| Go to beginning of file | `Ctrl+Home` | +| Go to end of file | `Ctrl+End` | +| Go to line N | `Ctrl+G` then type line number | +| Go to line and column | `Ctrl+G` then type `N:C` (e.g., `10:5`) | +| Go to symbol (heading in Markdown) | `Ctrl+Shift+O` | +| Go to definition | `F12` | +| Find in file | `Ctrl+F` | +| Next find result | `F3` | +| Previous find result | `Shift+F3` | +| Next error or warning | `F8` | +| Previous error or warning | `Shift+F8` | +| Open file by name | `Ctrl+P` then type filename | +| Toggle word wrap | `Alt+Z` | +| Toggle Tab focus mode | `Ctrl+M` (makes Tab move focus instead of indenting) | +| Increase/decrease font size | `Ctrl+=` / `Ctrl+-` | +| Breadcrumb navigation | `Ctrl+Shift+;` then arrow keys to navigate path segments | + +### Find in Current File (`Ctrl+F`) + +When the Find widget opens, three toggle buttons refine what matches: + +| Toggle | Shortcut | What It Does | +| --- | --- | --- | +| Match Case | `Alt+C` | Limits results to exact uppercase/lowercase | +| Match Whole Word | `Alt+W` | Matches full words only, not substrings | +| Use Regular Expression | `Alt+R` | Enables regex patterns in the search box | + +#### Screen reader interactions inside the Find widget + +- Toggles are announced as checkboxes - press `Space` to toggle each one +- Match count is announced as you type (example: `3 of 12 matches`) +- `F3` / `Shift+F3` move through matches while the widget stays open +- `Escape` closes the widget and returns focus to your last cursor position + +**Replace (`Ctrl+H`):** Opens the Find widget with a second input for the replacement text. + +- `Ctrl+Shift+1` - replace the current match +- `Ctrl+Alt+Enter` - replace all matches at once + +### Global Search Across the Workspace (`Ctrl+Shift+F`) + +The global Search panel has a rich filtering system - all keyboard-accessible: + +| Action | How | +| --- | --- | +| Open global search | `Ctrl+Shift+F` | +| Search input | Focus lands here automatically - type your query | +| Toggle case / word / regex | `Alt+C`, `Alt+W`, `Alt+R` (same as Find) | +| Include files filter | `Tab` to "files to include" field then type glob patterns | +| Exclude files filter | `Tab` to "files to exclude" field then type glob patterns | +| Collapse all results | `Ctrl+Shift+J` | +| Open a result | Navigate the result tree with `Up/Down Arrow` then `Enter` to open | + +#### Glob pattern examples for this workshop + +```text +docs/*.md - all Markdown files in the docs folder +*.agent.md - all agent definition files +.github/** - everything inside the .github folder +!node_modules/** - exclude node_modules folder +``` + +### Type-to-Filter in Tree Views + +In the **Explorer** file tree and the **Source Control** changes list, type characters to narrow visible items: + +1. Focus the Explorer (`Ctrl+Shift+E`) +2. Start typing a filename - a filter input appears at the bottom of the tree +3. The tree instantly narrows to matching files +4. Press `Escape` to clear the filter and restore full view + +### Go to Symbol with Inline Filtering (`Ctrl+Shift+O`) + +In any Markdown file, `Ctrl+Shift+O` opens a symbol picker populated by every heading. Type to narrow the list, then press `Enter` to jump. + +### Explorer (File Tree) Navigation + +| Action | Key | +| --- | --- | +| Navigate items | `Up/Down Arrow` | +| Expand folder | `Right Arrow` | +| Collapse folder | `Left Arrow` | +| Open file | `Enter` | +| Rename file | `F2` | +| Delete file | `Delete` | +| New file | `Ctrl+N` (then save with `Ctrl+S`) | + +### Learning Cards: Keyboard Navigation and Find + +
    +Screen reader users + +- Press `Ctrl+M` to toggle Tab focus mode -- when on, `Tab` moves focus between UI elements instead of inserting a tab character +- Use `Ctrl+G` then type a line number to jump directly to any line; type `10:5` to land at line 10, column 5 +- In the Find widget (`Ctrl+F`), match count is announced as you type (e.g., "3 of 12 matches"); press `F3` / `Shift+F3` to step through results +- **Keyboard Shortcuts editor (`Ctrl+K Ctrl+S`):** After typing a search query, your screen reader announces "Use Ctrl+Down Arrow to access the searched shortcut details" -- press `Ctrl+Down` to jump from the search input directly to the matching results table. Disable this hint with `accessibility.verbosity.keyboardShortcuts`. + +
    + +
    +Low vision users + +- Press `Alt+Z` to toggle word wrap so long lines stay visible without horizontal scrolling at high zoom +- Increase font size with `Ctrl+=` (Mac: `Cmd+=`) independently of your OS magnification for sharper text rendering +- The Find widget highlights all matches in the scrollbar gutter with colored ticks -- look for the bright orange markers + +
    + +
    +Sighted users + +- The breadcrumb bar above the editor (`Ctrl+Shift+;`) shows your file path and symbol hierarchy -- click any segment to navigate +- `Ctrl+P` opens the Quick Open file picker with fuzzy matching -- type a few letters of any filename to jump there instantly +- Use `Ctrl+Shift+O` in Markdown files to see all headings as a navigable symbol list + +
    + + +--- + +## 13. The Problems Panel + +The **Problems panel** (`Ctrl+Shift+M`) shows all errors, warnings, and informational messages from linters, compilers, and extensions for every open file in your workspace. + +### Opening the Problems Panel + +- **Keyboard:** `Ctrl+Shift+M` +- **Status Bar:** Click the errors/warnings count (bottom-left of window) +- **Menu Bar:** View then Problems +- **From the editor:** Press `F8` to jump to the next problem (cycles through errors in the current file) + +### Navigating Problems + +| Action | Shortcut | +| --- | --- | +| Open Problems panel | `Ctrl+Shift+M` | +| Next problem in editor | `F8` | +| Previous problem in editor | `Shift+F8` | +| Filter problems | Type in the filter box at the top of the panel | +| Jump to problem source | `Enter` on a problem row | + +### Understanding Problem Entries + +Each entry shows: + +- **Severity icon:** Error (red circle with X), Warning (yellow triangle), Info (blue circle with i) +- **Message:** Description of the problem +- **Source:** Which tool reported it (e.g., "markdownlint", "eslint", "Pylance") +- **File and line:** Where the problem is located + +### Learning Cards: Problems Panel + +
    +Screen reader users + +- Press `Ctrl+Shift+M` to focus the Problems panel. Your screen reader announces the total count. +- Each problem is read as: severity, message, source, file name, and line number +- Press `Enter` on any problem to jump directly to that line in the editor +- Use `F8` / `Shift+F8` from inside the editor to cycle through problems without opening the panel +- The status bar errors/warnings count updates in real time and is announced when you Tab to it + +
    + +
    +Low vision users + +- Problems are color-coded: red for errors, yellow for warnings, blue for info +- The errors/warnings count in the Status Bar gives a quick overview +- Click any problem to jump to the exact file and line +- Filter the panel by typing keywords to reduce visual noise + +
    + +
    +Sighted users + +- The Problems panel is in the bottom Panel area alongside Terminal and Output +- Red squiggly underlines in the editor correspond to problems in this panel +- Click any problem to navigate to its location +- Use the filter and severity toggles to focus on what matters + +
    + + +--- + +## 14. The Terminal + +VS Code includes a fully featured integrated terminal. You can run shell commands, Git operations, and scripts without leaving the editor. + +### Opening and Managing Terminals + +| Action | Shortcut | +| --- | --- | +| Toggle terminal | `` Ctrl+` `` (backtick) | +| New terminal | `` Ctrl+Shift+` `` | +| Split terminal | `Ctrl+Shift+5` | +| Next terminal | Focus terminal then `Ctrl+PageDown` | +| Previous terminal | Focus terminal then `Ctrl+PageUp` | +| Kill terminal | Type `exit` or use the trash icon | + +### Terminal Shell Integration + +VS Code's shell integration enhances the terminal with: + +- **Command decoration marks** - visual indicators showing where each command started and whether it succeeded or failed +- **Run recent command** (`Ctrl+R` in terminal) - VS Code's quick pick of your recent commands, searchable by name +- **Terminal IntelliSense** (`Ctrl+Space`) - completion suggestions for shell commands, file paths, and arguments + +Enable Terminal IntelliSense: Settings (`Ctrl+,`) then search `terminal.integrated.suggest.enabled` then set to `on`. + +### Terminal Accessibility + +| Feature | How to Access | +| --- | --- | +| Accessible Help in terminal | `Alt+H` while terminal is focused | +| Navigate terminal output lines | `` Alt+Ctrl+PageUp `` / `` Alt+Ctrl+PageDown `` | +| Select terminal output | `Shift+Arrow keys` while in the terminal | +| Minimum contrast ratio | Settings then search `terminal.integrated.minimumContrastRatio` (default: 4.5 for WCAG AA) | + +### Learning Cards: Terminal + +
    +Screen reader users + +- Press `` Ctrl+` `` to toggle the terminal. Your screen reader announces "Terminal" and the shell prompt. +- The terminal acts like a standard text input - type commands and press `Enter` +- Press `Alt+H` while in the terminal for a full list of terminal-specific keyboard shortcuts +- Use `Ctrl+R` to open the "Run Recent Command" picker - a searchable list of your recent commands +- Terminal Navigation Mode: Commands for moving between lines help when reviewing output with a screen reader. + +
    + +
    +Low vision users + +- VS Code enforces a minimum contrast ratio (4.5:1 by default) for terminal text +- Increase terminal font size: Settings then search `terminal.integrated.fontSize` +- Terminal themes inherit from your VS Code color theme - High Contrast themes apply here too +- Use `Ctrl+=` / `Ctrl+-` to zoom the entire window including the terminal + +
    + +
    +Sighted users + +- The terminal appears in the bottom Panel - drag the top border to resize +- Click the `+` icon to create new terminals, the split icon to split, the trash icon to close +- Right-click in the terminal for copy/paste and other context menu options +- Multiple terminal tabs let you keep different shells open simultaneously + +
    + + +--- + +## 15. Copilot Chat Window + +The **Copilot Chat** window (`Ctrl+Shift+I`) is your conversational AI assistant within VS Code. It can answer questions, generate code, explain code, fix problems, and help with documentation. + +### Opening Copilot Chat + +| Method | Shortcut | +| --- | --- | +| Chat view (sidebar) | `Ctrl+Shift+I` | +| Inline chat (in editor) | `Ctrl+I` | +| Quick chat (floating) | `Ctrl+Shift+Alt+L` | +| Command Palette | `Ctrl+Shift+P` then type `Chat: Open` | + +### Chat Modes + +| Mode | What It Does | +| --- | --- | +| **Ask** | Question-answer mode - explain code, answer questions, generate snippets | +| **Edit** | Multi-file editing mode - Copilot proposes edits across your workspace | +| **Agent** | Autonomous mode - Copilot can run terminal commands, create files, and perform complex tasks | + +Switch modes using the mode picker at the top of the Chat view, or use keyboard shortcuts: +- `workbench.action.chat.openAsk` - Ask mode +- `workbench.action.chat.openEdit` - Edit mode +- `workbench.action.chat.openAgent` - Agent mode + +### Using Chat Participants + +Type `@` in the chat input to see available participants: + +- **@workspace** - Ask questions about your entire codebase +- **@vscode** - Ask about VS Code settings and features +- **@terminal** - Run commands or explain terminal output + +### Learning Cards: Copilot Chat + +
    +Screen reader users + +- Press `Ctrl+Shift+I` to open Chat. Focus lands in the text input - start typing your question. +- After submitting, wait for the response to complete (audio cue plays if `accessibility.signals.chatResponseReceived` is on) +- Press `Alt+F2` (Accessible View) to read the complete response in a clean, navigable text view +- Navigate response content with `Up/Down Arrow` in the Accessible View +- Press `Escape` to return to the chat input for follow-up questions + +
    + +
    +Low vision users + +- The Chat view appears in the sidebar and respects your zoom level and font settings +- Copilot responses include syntax-highlighted code blocks +- Use `Ctrl+I` for inline chat that appears right where your cursor is in the editor +- Resize the Chat panel by dragging its border for a comfortable reading width + +
    + +
    +Sighted users + +- Click the Copilot icon in the sidebar or use `Ctrl+Shift+I` +- Code blocks in responses have a "Copy" button and an "Insert at Cursor" button +- The mode picker at the top lets you switch between Ask, Edit, and Agent modes +- Use `@workspace` to ask questions about your specific project context + +
    + +### Agent Mode: Question Carousel and Terminal Focus + +When Copilot's Agent mode is running a terminal command and needs your input -- such as a password prompt, confirmation, or interactive installer question -- VS Code displays a **question carousel** in the Chat panel. The carousel shows what the terminal is asking and lets you respond without switching focus to the terminal manually. + +**Keyboard shortcuts for the question carousel:** + +| Shortcut | Action | +| --- | --- | +| `Alt+T` | Jump directly from the question carousel back to the terminal | +| `Tab` | Navigate carousel buttons (Confirm, Dismiss, Focus Terminal) | +| `Enter` | Activate the focused button | + +> **Screen reader tip:** When the question carousel appears, your screen reader announces the question and the available buttons. The Focus Terminal button's ARIA label includes the `Alt+T` keybinding hint so you can hear it is available. Press `Alt+T` to move focus to the terminal and type your answer directly. + +**Suppressing carousel hints:** The ARIA label on the carousel includes a navigation hint by default. To suppress this announcement, set `accessibility.verbosity.chatQuestionCarousel` to `false` in Settings. + + +--- + +## 16. Accessible Help, Accessible View, and Accessible Diff + +> **See also:** [Appendix G: VS Code Reference](appendix-g-vscode-reference.md) has a complete keyboard shortcut reference for all VS Code accessibility features. + +VS Code has a family of purpose-built accessibility features that give screen reader users complete, structured access to content that is otherwise conveyed visually or through dynamic regions. These three are the most important to know before working with Copilot and diffs. + + +### 16.1 Accessible Help - Context-Aware Keyboard Guide + +Every interactive area of VS Code - the editor, the terminal, the diff view, the Copilot Chat panel - has its own keyboard commands. **Accessible Help** surfaces those commands in a plain-text, fully readable dialog, tailored to exactly where your focus is right now. + +#### How to open Accessible Help + +| Context | Shortcut | +| --- | --- | +| Inside the editor | `Alt+H` | +| Inside the terminal | `Alt+H` | +| Inside a diff view | `Alt+H` | +| Inside Copilot Chat | `Alt+H` | +| Any VS Code widget | `Alt+H` | + +The dialog is announced with a heading and a complete list of keyboard shortcuts for that specific widget. Navigate with `Up/Down Arrow`. Press `Escape` to dismiss and return focus to where you were. + +**Why this matters:** You do not need to memorize every shortcut in every panel. Open Accessible Help in any unfamiliar area and VS Code will tell you exactly what you can do there. It is the built-in answer to "what can I press from here?" + +#### Example output when pressing `Alt+H` in the editor + +```text +Accessible Help: Editor + +Press F8 to jump to the next error or warning. +Press Shift+F8 to jump to the previous error or warning. +Press Ctrl+Shift+M to open the Problems panel. +Press F12 to go to a definition. +Press Alt+F12 to peek a definition inline. +Press Ctrl+Shift+O to go to a symbol in this file. +Press Alt+F2 to open the Accessible View. +Press Alt+H to view this help content again. +``` + +Use Accessible Help as your first action whenever you land somewhere new in VS Code. + + +### 16.2 Accessible View - Reading Dynamic and Streamed Content + +**Accessible View** (`Alt+F2`) gives screen reader users a clean, static, fully readable version of content that is otherwise presented dynamically, in tooltips, or in streaming form. + +#### How to open Accessible View + +| Shortcut | When to Use | +| --- | --- | +| `Alt+F2` | Open Accessible View for the currently focused element | +| `Escape` | Close Accessible View and return to the editor | + +#### What Accessible View provides + +| Content Type | Without Accessible View | With Accessible View (`Alt+F2`) | +| --- | --- | --- | +| Copilot Chat response | Fragmented - announced as tokens stream in | Full complete response, read sequentially with Arrow keys | +| Inline Copilot suggestion | Ghost text - may not be announced | Announced as "Suggestion: [full text]" | +| Hover documentation | Popup tooltip - announced only briefly | Full content, fully navigable with Arrow keys | +| Error / warning details | On-focus message only | Full error text, error code, and suggested fix | +| Terminal output | May be truncated by live region limits | Full output in review mode with scroll | +| Notification banners | Announced once and dismissed | Persistent readable content until you close it | + +#### Recommended workflow for Copilot Chat + +1. Type your prompt in the Chat input +2. Wait for the response to finish (NVDA: live region announcements stop; JAWS: typing indicator disappears; VoiceOver: busy state clears) +3. Press `Alt+F2` - Accessible View opens with the complete response +4. Navigate with `Up/Down Arrow` through the response +5. Press `Escape` to return to the chat input + +#### Recommended workflow for hover documentation + +1. Navigate to a symbol or link with keyboard +2. Press `Ctrl+K I` to trigger hover programmatically (no mouse needed) +3. Press `Alt+F2` to open Accessible View with the full hover content +4. Press `Escape` to dismiss + + +### 16.3 Accessible Diff Viewer - Reading Changes Without Visual Scanning + +When you open a file diff - in Source Control, in the GitHub PR extension, or during a merge conflict - VS Code normally shows it as a side-by-side or inline visual view. For screen reader users, tracking which lines changed and how can be difficult without a structured reading mode. + +**The Accessible Diff Viewer** presents the same diff as a plain, navigable list of changed lines - organized by hunk, labeled by change type (added, removed, unchanged), with the line number announced for each line. + +#### How to open the Accessible Diff Viewer + +| Shortcut | What Happens | +| --- | --- | +| `F7` | Move to the next diff hunk (from within the diff editor) | +| `Shift+F7` | Move to the previous diff hunk | +| Command Palette | `Ctrl+Shift+P` then type "Open Accessible Diff Viewer" | + +#### What the Accessible Diff Viewer announces + +For each hunk (a block of related changes), the viewer announces: + +- The hunk number and total hunk count (`Hunk 2 of 5`) +- The line range affected +- Each line, prefixed with its change type: + +```text +Hunk 1 of 3 - lines 12 to 18 + Unchanged: ## Screen Reader Cheat Sheet +- Line removed: > Quick reference for NVDA users. ++ Line added: > Quick reference for NVDA, JAWS, and VoiceOver users. + Unchanged: + Unchanged: Use this document during the workshop. +``` + +This gives you the complete picture of what changed, in reading order, without visual diff scanning. + +#### Practical uses during this workshop + +- **Before approving a PR:** Open the diff then `F7` to enter the first hunk then navigate each change then `F7` for next hunk then repeat until all hunks reviewed +- **During a merge conflict:** The conflict markers (`<<<<<<<`, `=======`, `>>>>>>>`) appear as lines in the viewer - you can read both conflicting versions before deciding which to keep +- **After Copilot generates an edit:** Open the diff (`Ctrl+Shift+G` then navigate to the changed file then `Enter`) then review exactly what Copilot changed vs. what was there before + +#### Audio cues for diffs + +With `accessibility.signals.diffLineInserted` and `accessibility.signals.diffLineDeleted` both set to `on` in Settings, VS Code plays a distinct tone when your cursor moves over an added line (higher pitched) or a removed line (lower pitched). You receive change-type information through sound before the line text is announced. + +### Learning Cards: Accessible Help, View, and Diff + +
    +Screen reader users + +- Press `Alt+H` in any VS Code panel to open Accessible Help -- it lists every keyboard shortcut available in your current context +- Press `Alt+F2` to open Accessible View for Copilot responses, hover documentation, or terminal output -- read the full content with arrow keys +- In a diff view, press `F7` to enter the Accessible Diff Viewer and step through changes hunk by hunk with line-level change-type announcements + +
    + +
    +Low vision users + +- Accessible View (`Alt+F2`) renders Copilot responses as plain text in a scrollable pane -- easier to read at high zoom than the streaming chat panel +- In diff views, enable `accessibility.signals.diffLineInserted` for an audible cue on added lines so you do not rely solely on color +- The Accessible Diff Viewer text uses the same font size as your editor -- zoom settings apply automatically + +
    + +
    +Sighted users + +- The diff editor shows added lines in green and removed lines in red, with a gutter icon indicating the change type +- Click the inline "Copy" or "Insert at Cursor" buttons on code blocks in Copilot Chat responses for quick use +- Use the minimap colored regions on the right to spot clusters of changes in long diffs at a glance + +
    + + +--- + +## 17. Accessibility Signals + +VS Code communicates editor state through **Accessibility Signals** -- non-verbal cues that tell you what is happening as you move through code, run commands, and interact with Copilot. Signals replaced the older "Audio Cues" system (deprecated since VS Code 1.85) and are significantly more powerful. + +> **Official documentation:** [VS Code Accessibility -- Accessibility Signals](https://code.visualstudio.com/docs/configure/accessibility/accessibility#_accessibility-signals) + +### How Signals Work: The Dual-Channel Architecture + +Every accessibility signal has **two independent channels** that you control separately: + +| Channel | What It Does | Who Benefits | +| --- | --- | --- | +| **Sound** | Plays a short audio tone | Everyone -- sighted users, low vision users, and screen reader users all benefit from audio feedback | +| **Announcement** | Sends a status message that screen readers and braille displays announce | Primarily screen reader and braille users | + +Each channel accepts one of these values: + +| Value | Meaning | +| --- | --- | +| `"on"` | Always enabled regardless of screen reader state | +| `"off"` | Always disabled | +| `"auto"` | Enabled only when VS Code detects a screen reader (default for most announcement channels) | +| `"userGesture"` | Enabled only when the user explicitly triggers the action (used by Save and Format signals to avoid noise from auto-save) | + +This means you can enable sounds for everyone while keeping announcements on `auto` so they only fire when a screen reader is attached. Or you can turn on announcements without sounds. Full independent control. + +### Discovering Signals: The Two Essential Commands + +VS Code provides two commands that let you **browse every available signal, hear what each one sounds like, and toggle them on or off** without editing settings.json: + +| Command (Command Palette `Ctrl+Shift+P`) | What It Does | +| --- | --- | +| **Help: List Signal Sounds** | Opens a picker listing every signal sound. As you arrow through the list, each sound plays so you can hear it. Press `Enter` to toggle the selected signal on or off. | +| **Help: List Signal Announcements** | Same experience for announcement messages. Arrow through the list to hear the announcement text read by your screen reader, then toggle. | + +These are the fastest way to configure signals. You do not need to memorize setting names. + +
    +Screen reader users + +The **Help: List Signal Announcements** command is especially valuable. It lists every announcement message VS Code can send to your screen reader. Arrow through the list -- your screen reader reads each announcement label. Press `Enter` to toggle. This is faster than searching through Settings and ensures you hear the exact phrasing VS Code will use. + +
    + +
    +Low vision users + +Even if you do not use a screen reader, signal sounds add a valuable audio layer. When you land on an error line, a distinct error tone plays before you even read the squiggly underline. When a terminal command finishes, a completion chime saves you from watching the terminal. Open **Help: List Signal Sounds** to preview and enable the ones that help your workflow. + +
    + +
    +Sighted users + +Signal sounds are not just for accessibility -- they improve any workflow. Enable `taskCompleted` and `taskFailed` to know when builds finish while you are reading documentation in another tab. Enable `chatResponseReceived` to hear when Copilot finishes generating while you work in a different file. Open **Help: List Signal Sounds** to hear what each one sounds like. + +
    + +### Volume Control + +Control signal volume independently from your system volume: + +| Setting | Range | Default | Purpose | +| --- | --- | --- | --- | +| `accessibility.signalOptions.volume` | 0 -- 100 | 50 | Master volume for all accessibility signal sounds | + +Set this in Settings (`Ctrl+,`) by searching "signal volume" or add it to `settings.json`: + +```json +{ + "accessibility.signalOptions.volume": 70 +} +``` + +### Complete Signal Reference + +VS Code registers **30+ accessibility signals** organized into categories. The tables below list every signal, its setting key, the sound it plays, and whether it supports announcements. + +#### Editor Signals + +These fire when your cursor moves to a line or position with a specific marker: + +| Setting Key | Fires When | Sound | Announcement | +| --- | --- | --- | --- | +| `accessibility.signals.lineHasError` | Cursor moves to a line containing an error | Error tone | "Error on Line" | +| `accessibility.signals.lineHasWarning` | Cursor moves to a line containing a warning | Warning tone (lower pitch) | "Warning on Line" | +| `accessibility.signals.positionHasError` | Cursor moves to the exact position of an error | Error tone | "Error" | +| `accessibility.signals.positionHasWarning` | Cursor moves to the exact position of a warning | Warning tone | "Warning" | +| `accessibility.signals.lineHasFoldedArea` | Cursor moves to a line with a collapsed/folded region | Folded area tone | "Folded" | +| `accessibility.signals.lineHasBreakpoint` | Cursor moves to a line with a breakpoint | Break tone | "Breakpoint" | +| `accessibility.signals.lineHasInlineSuggestion` | Cursor moves to a line with a Copilot ghost text suggestion | Quick fix tone | -- | +| `accessibility.signals.nextEditSuggestion` | Next Edit Suggestion appears on the line | Next edit tone | "Next Edit Suggestion" | +| `accessibility.signals.noInlayHints` | Cursor is on a line with no inlay hints | Error tone | "No Inlay Hints" | + +> **Line vs Position signals:** The `lineHasError` signal fires once when your cursor enters the line. The `positionHasError` signal fires when the cursor reaches the exact character where the error starts. Both can be enabled simultaneously for layered feedback. + +#### Diff Signals + +These fire when navigating changes in the diff editor or reviewing pull requests: + +| Setting Key | Fires When | Sound | +| --- | --- | --- | +| `accessibility.signals.diffLineInserted` | Cursor moves over an added (green) line | Inserted tone (higher pitch) | +| `accessibility.signals.diffLineDeleted` | Cursor moves over a removed (red) line | Deleted tone (lower pitch) | +| `accessibility.signals.diffLineModified` | Cursor moves over a modified line | Modified tone | + +These are critical for pull request review. You hear the type of change before reading the content. + +#### Terminal Signals + +| Setting Key | Fires When | Sound | Announcement | +| --- | --- | --- | --- | +| `accessibility.signals.terminalBell` | Terminal sends a bell character | Bell tone | -- | +| `accessibility.signals.terminalQuickFix` | Terminal detects a quick fix suggestion | Quick fix tone | "Quick Fix" | +| `accessibility.signals.terminalCommandSucceeded` | A terminal command exits successfully | Command succeeded tone | -- | +| `accessibility.signals.taskCompleted` | A VS Code Task finishes successfully | Task completed tone | -- | +| `accessibility.signals.taskFailed` | A VS Code Task exits with an error | Task failed tone | -- | + +> **Workshop tip:** Enable `taskCompleted` and `taskFailed` immediately. When you run `git push` or `npm test` in the terminal, you hear whether it succeeded without switching back to the terminal panel. + +#### Chat and Copilot Signals + +| Setting Key | Fires When | Sound | Announcement | +| --- | --- | --- | --- | +| `accessibility.signals.chatRequestSent` | You send a message to Copilot Chat | Request sent tone | -- | +| `accessibility.signals.chatResponsePending` | Copilot is generating a response (loops) | Progress tone | -- | +| `accessibility.signals.chatResponseReceived` | Copilot finishes generating | One of 4 random response tones | -- | +| `accessibility.signals.chatEditModifiedFile` | Copilot Edits modifies a file in your workspace | Modified file tone | -- | +| `accessibility.signals.chatUserActionRequired` | Copilot needs you to take an action (accept/reject) | Action required tone | -- | +| `accessibility.signals.editsKept` | You accept Copilot's suggested edits | Edits kept tone | -- | +| `accessibility.signals.editsUndone` | You reject/undo Copilot's suggested edits | Edits undone tone | -- | + +> **Why four response sounds?** `chatResponseReceived` plays a randomly chosen variant each time (responseReceived1 through responseReceived4). This prevents habituation -- your brain stays alert to the signal instead of filtering it out after hearing the same sound repeatedly. This is an intentional accessibility design pattern. + +#### Debug Signals + +| Setting Key | Fires When | Sound | Announcement | +| --- | --- | --- | --- | +| `accessibility.signals.onDebugBreak` | Debugger stops on a breakpoint | Break tone | "Breakpoint" | + +#### Editor Action Signals + +These fire on user-triggered actions and use the `"userGesture"` value to distinguish manual saves from auto-saves: + +| Setting Key | Fires When | Sound | +| --- | --- | --- | +| `accessibility.signals.save` | File is saved | Save tone | +| `accessibility.signals.format` | File is formatted | Format tone | +| `accessibility.signals.clear` | Terminal or output is cleared | Clear tone | + +Set these to `"userGesture"` rather than `"on"` if auto-save is enabled, to avoid a sound on every keystroke pause: + +```json +{ + "accessibility.signals.save": { + "sound": "userGesture", + "announcement": "off" + } +} +``` + +#### Voice Signals + +| Setting Key | Fires When | Sound | +| --- | --- | --- | +| `accessibility.signals.voiceRecordingStarted` | Voice dictation begins | Recording started tone | +| `accessibility.signals.voiceRecordingStopped` | Voice dictation ends | Recording stopped tone | + +#### Code Action Signals + +| Setting Key | Fires When | Sound | +| --- | --- | --- | +| `accessibility.signals.codeActionTriggered` | A code action (quick fix, refactor) is triggered | Code action triggered tone | +| `accessibility.signals.codeActionApplied` | A code action is applied to the code | Code action applied tone | + +### Debounce Settings for Position Signals + +When you hold an arrow key and your cursor moves rapidly through lines, position-based signals (error/warning at position) could fire dozens of times per second. VS Code debounces these by default: + +| Setting | Default | Purpose | +| --- | --- | --- | +| `accessibility.signalOptions.debouncePositionChanges` | `true` | Enable position signal debouncing | +| `accessibility.signalOptions.experimental.delays.errorAtPosition` | `{ sound: 300, announcement: 3000 }` | Millisecond delay before error-at-position fires | +| `accessibility.signalOptions.experimental.delays.warningAtPosition` | `{ sound: 300, announcement: 3000 }` | Millisecond delay before warning-at-position fires | +| `accessibility.signalOptions.experimental.delays.general` | `{ sound: 300, announcement: 3000 }` | Default delay for all other position-based signals | + +The announcement delay is intentionally longer (3 seconds) because screen reader interruptions are more disruptive than brief sounds. + +### Recommended Workshop Profile + +Add this to your VS Code `settings.json` (`Ctrl+Shift+P` then "Preferences: Open User Settings (JSON)"): + +```json +{ + "editor.accessibilitySupport": "on", + + "accessibility.signalOptions.volume": 70, + + "accessibility.signals.lineHasError": { + "sound": "on", + "announcement": "auto" + }, + "accessibility.signals.lineHasWarning": { + "sound": "on", + "announcement": "auto" + }, + "accessibility.signals.lineHasFoldedArea": { + "sound": "on", + "announcement": "auto" + }, + "accessibility.signals.lineHasBreakpoint": { + "sound": "on", + "announcement": "auto" + }, + "accessibility.signals.taskCompleted": { + "sound": "on", + "announcement": "auto" + }, + "accessibility.signals.taskFailed": { + "sound": "on", + "announcement": "auto" + }, + "accessibility.signals.terminalCommandSucceeded": { + "sound": "on", + "announcement": "off" + }, + "accessibility.signals.chatResponseReceived": { + "sound": "on", + "announcement": "auto" + }, + "accessibility.signals.diffLineInserted": { + "sound": "on", + "announcement": "off" + }, + "accessibility.signals.diffLineDeleted": { + "sound": "on", + "announcement": "off" + }, + "accessibility.signals.save": { + "sound": "userGesture", + "announcement": "off" + }, + + "editor.minimap.enabled": false, + "editor.renderWhitespace": "none", + "editor.wordWrap": "on" +} +``` + +This profile enables core sounds for everyone and sets announcements to `auto` so they activate only when a screen reader is detected. The `save` signal uses `userGesture` to avoid noise from auto-save. Diff signals are sound-only because rapid line navigation with announcements would overwhelm a screen reader. + +
    +Screen reader users + +Focus on announcements more than sounds. Set the signals you care about most to `"announcement": "on"` (not just `"auto"`) to guarantee they fire even if VS Code does not detect your screen reader. The most valuable announcements for this workshop are: + +- `lineHasError` -- "Error on Line" as you navigate code +- `taskCompleted` / `taskFailed` -- know when git operations finish +- `chatResponseReceived` -- know when Copilot is done responding +- `lineHasBreakpoint` -- confirm breakpoint placement during debugging + +Use **Help: List Signal Announcements** (`Ctrl+Shift+P` then type "List Signal Announcements") to hear and toggle each one. + +
    + +
    +Low vision users + +Sounds give you status confirmation without needing to find and read small visual indicators. The most impactful signals: + +- `lineHasError` + `lineHasWarning` -- hear errors as you navigate instead of scanning for red/yellow squiggles +- `diffLineInserted` + `diffLineDeleted` -- hear change types in pull request diffs before reading the color coding +- `taskCompleted` + `taskFailed` -- audio confirmation when terminal commands finish +- `chatResponseReceived` -- know when Copilot is done while you read other content + +Raise the volume with `accessibility.signalOptions.volume` (try 80 or 90) if your system volume competes with screen magnification software audio. + +
    + +
    +Sighted users + +Do not skip this section because you can see the screen. Signal sounds make you faster: + +- **Build notifications:** Enable `taskCompleted` and `taskFailed`. Start a build, switch to writing code, hear the chime when it finishes. +- **Copilot flow:** Enable `chatResponseReceived`. Ask Copilot a question, continue editing, hear the response tone. +- **Error awareness:** Enable `lineHasError`. As you type, you hear immediately when you introduce a syntax error without glancing at the Problems panel. +- **Code review:** Enable diff signals. Arrow through a PR diff and hear inserted/deleted/modified tones. Your eyes stay on the code while your ears track the change type. + +Start with **Help: List Signal Sounds** to preview each tone and build your personal selection. + +
    + +### Migrating from Legacy Audio Cues + +If you previously configured the older `audioCues.*` settings (deprecated since VS Code 1.85), VS Code automatically maps them to the new `accessibility.signals.*` namespace. However, the new settings offer the dual sound/announcement structure that the old settings did not have. Review your configured signals using **Help: List Signal Sounds** and **Help: List Signal Announcements** to take advantage of the new independent controls. + +**Note:** `minimap.enabled: false` in the recommended profile removes the visual minimap that adds no value for screen reader users and can cause some accessibility tools to announce additional regions. + +### Learning Cards: Accessibility Signals + +
    +Screen reader users + +- Run `Help: List Signal Sounds` from the Command Palette (`Ctrl+Shift+P`) to preview every available signal tone and decide which to enable +- Enable `accessibility.signals.lineHasError` so you hear an immediate tone when your cursor lands on a line with an error -- no need to open the Problems panel +- Set signals to `"announcement"` channel if you prefer spoken labels (e.g., "error on line") over tones + +
    + +
    +Low vision users + +- Signals provide a second channel of awareness -- hearing a "task completed" chime means you can keep your magnifier focused on your editor instead of watching the terminal +- Enable `accessibility.signals.chatResponseReceived` to get an audible notification when Copilot finishes generating a response +- Pair error signals with High Contrast themes so both color and sound reinforce error locations + +
    + +
    +Sighted users + +- Accessibility signals are opt-in -- open Settings (`Ctrl+,`) and search `accessibility.signals` to see all available signals with toggle switches +- Enable diff line signals (`diffLineInserted`, `diffLineDeleted`) for an extra audio channel during code review +- The Status Bar shows a speaker icon when signals are active; click it for quick access to signal settings + +
    + + +--- + +## 18. VS Code Speech - Voice Input and Output + +The VS Code Speech extension adds speech-to-text and text-to-speech capabilities to VS Code. All voice processing happens locally on your machine - no audio data is sent to any online service. This makes it useful for dictation, talking to Copilot Chat, and having Chat responses read aloud. + +### Installing VS Code Speech + +1. Open Extensions: `Ctrl+Shift+X` (Mac: `Cmd+Shift+X`) +2. Search for **VS Code Speech** +3. Find **VS Code Speech** (publisher: Microsoft, identifier: `ms-vscode.vscode-speech`) +4. Press `Enter` to open the extension detail page, then `Tab` to "Install" and press `Enter` + +After installation, a microphone icon appears in all Chat input fields and new voice commands become available in the Command Palette. + +> **Microphone permissions:** On macOS, go to System Settings, Privacy and Security, Microphone, and confirm Visual Studio Code is enabled. On Windows, go to Settings, Privacy and security, Microphone, and confirm that "Let desktop apps access your microphone" is on. Without this permission, voice input fails silently. + +### Editor Dictation - Type with Your Voice + +Editor dictation lets you speak and have your words appear as text wherever your cursor is. This works in the code editor, the SCM commit input box, and the comments field when reviewing pull requests. + +| Action | Windows/Linux | macOS | +| ------ | ------------- | ----- | +| Start dictation | `Ctrl+Alt+V` | `Cmd+Alt+V` | +| Stop dictation | `Escape` | `Escape` | +| Walky-talky mode | Press and hold `Ctrl+Alt+V`, speak, release to stop | Press and hold `Cmd+Alt+V`, speak, release to stop | + +When dictation is active, a small microphone icon appears at the cursor position. Speak naturally and your words are transcribed into text. Press `Escape` to stop. + +**Walky-talky mode:** Press and hold the keyboard shortcut instead of tapping it. Voice recognition stays active as long as you hold the keys. When you release, dictation stops automatically. This is the fastest way to dictate a short phrase. + +
    +Screen reader users (NVDA / JAWS / VoiceOver) + +- When dictation starts, the accessibility signal `voiceRecordingStarted` plays (if configured in section 17). Your screen reader may also announce "Recording started." +- Dictated text appears at the cursor position and is announced by your screen reader as it is inserted, just like typed text. +- Press `Escape` to stop. The `voiceRecordingStopped` signal plays. +- If you do not hear dictated text being announced, check that your screen reader is in focus mode (NVDA: `Insert+Space` to toggle) so it reads editor changes. + +
    + +
    +Low vision users + +- The microphone icon that appears at the cursor is small. At 200%+ zoom it may be hard to spot, but dictation works regardless of whether you see the icon. +- Dictated text appears at your configured editor font size with full contrast - no ghost text or gray previews. +- **Check status bar:** When dictation is active, the status bar shows a recording indicator. Press `F6` to cycle to the status bar and confirm. + +
    + +### Voice in Copilot Chat - Talk to Copilot + +Instead of typing prompts, you can speak them. This works in the Chat panel, inline chat, and quick chat. + +| Action | Windows/Linux | macOS | +| ------ | ------------- | ----- | +| Start voice chat (auto-selects best location) | `Ctrl+I` | `Cmd+I` | +| Start voice in Chat panel specifically | Command Palette: "Chat: Voice Chat in Chat View" | Same | +| Start inline voice chat | Command Palette: "Chat: Inline Voice Chat" | Same | +| Start quick voice chat | Command Palette: "Chat: Quick Voice Chat" | Same | + +When voice chat is active, a microphone icon appears in the chat input field. Speak your prompt naturally. When you pause, the prompt is automatically submitted. + +> **Automatic submission:** By default, VS Code submits your voice prompt after a pause. You can adjust the wait time with the `accessibility.voice.speechTimeout` setting (in milliseconds), or set it to `0` to disable auto-submit entirely so you can review before sending. + +**Walky-talky mode in chat:** Press and hold `Ctrl+I` (Mac: `Cmd+I`). Speak your prompt. When you release the keys, voice recognition stops and the prompt is submitted automatically. + +
    +Screen reader users (NVDA / JAWS / VoiceOver) + +- `Ctrl+I` with Speech installed starts voice input. If the Chat view is not focused, it opens the Chat view. If you are in the editor, it opens inline chat. +- Speak your prompt instead of typing. Your screen reader announces the transcribed text as it appears in the input field. +- When the response arrives, press `Alt+F2` (Accessible View) to read it at your own pace, just as you would with a typed prompt. +- The automatic submission after a pause may catch you off guard. If you need more time to compose a multi-sentence prompt, set `accessibility.voice.speechTimeout` to `0` and submit manually with `Ctrl+Enter`. + +
    + +### Text-to-Speech - Listen to Chat Responses + +VS Code Speech can read Copilot Chat responses aloud. Each chat response shows a speaker icon you can activate to hear that specific response. + +#### Automatic read-aloud after voice input + +Enable this setting to have every Chat response automatically spoken aloud when you used voice to ask the question: + +```json +{ + "accessibility.voice.autoSynthesize": true +} +``` + +When auto-synthesize is on: + +1. You speak a question using voice chat +2. Copilot responds in text +3. The response is automatically read aloud +4. To stop playback mid-sentence, press `Escape` or activate the stop icon + +#### Manual read-aloud for any response + +Even without `autoSynthesize`, every Chat response has a speaker icon. Activate it to hear that specific response read aloud. This works for responses from typed prompts too, not just voice prompts. + +
    +Screen reader users (NVDA / JAWS / VoiceOver) + +- Text-to-speech uses a separate audio channel from your screen reader. Both may speak at the same time, which can be confusing. +- **Recommended approach:** If you use a screen reader, you may prefer to keep `autoSynthesize` off and use Accessible View (`Alt+F2`) to read responses yourself. The text-to-speech voice is more useful for sighted users who want a hands-free experience. +- If you do want to try text-to-speech alongside your screen reader, reduce your screen reader volume or temporarily mute it while Copilot speaks. + +
    + +### "Hey Code" - Hands-Free Activation + +You can configure VS Code to listen continuously for the wake phrase "Hey Code" to start a voice chat session without touching the keyboard. + +Enable it in Settings: + +```json +{ + "accessibility.voice.keywordActivation": "chatInView" +} +``` + +| Setting value | What happens when you say "Hey Code" | +| ------------- | ------------------------------------- | +| `"off"` | Disabled (default) | +| `"chatInView"` | Opens voice chat in the Chat view | +| `"quickChat"` | Opens voice quick chat (floating) | +| `"inlineChat"` | Opens voice inline chat in the editor | +| `"chatInContext"` | Opens voice chat in whichever chat location is most relevant | + +When "Hey Code" listening is active, a microphone icon appears in the status bar to show that VS Code is listening for the wake phrase. + +> **Privacy note:** Even with "Hey Code" enabled, all processing is local. No audio leaves your machine. The extension listens for the wake phrase only and starts transcription only after detecting it. + +### Language Configuration + +VS Code Speech supports 26 languages. By default it matches your VS Code display language. To change it: + +```json +{ + "accessibility.voice.speechLanguage": "en-US" +} +``` + +When you start speech recognition for the first time with a new language, VS Code may install an additional language extension automatically. + +### All Voice Settings Reference + +| Setting | Default | Purpose | +| ------- | ------- | ------- | +| `accessibility.voice.speechLanguage` | `"auto"` | Language for speech recognition and synthesis. `"auto"` uses your VS Code display language. | +| `accessibility.voice.speechTimeout` | `1250` | Milliseconds of silence before auto-submitting a voice chat prompt. Set to `0` to disable auto-submit. | +| `accessibility.voice.autoSynthesize` | `false` | Automatically read Chat responses aloud when voice was used as input. | +| `accessibility.voice.keywordActivation` | `"off"` | Enable "Hey Code" wake phrase. Values: `"off"`, `"chatInView"`, `"quickChat"`, `"inlineChat"`, `"chatInContext"`. | + +### All Voice Commands Reference + +| Command | Default shortcut | What it does | +| ------- | ---------------- | ------------ | +| Voice: Start Dictation in Editor | `Ctrl+Alt+V` (Mac: `Cmd+Alt+V`) | Begin dictating text at the cursor | +| Voice: Stop Dictation in Editor | `Escape` | Stop dictation | +| Chat: Start Voice Chat | `Ctrl+I` (Mac: `Cmd+I`) | Start voice input in the most appropriate chat location | +| Chat: Voice Chat in Chat View | None | Start voice chat specifically in the Chat panel | +| Chat: Inline Voice Chat | None | Start voice chat inline in the editor | +| Chat: Quick Voice Chat | None | Start voice chat in the floating quick chat | +| Chat: Stop Listening and Submit | None | End voice input and submit the prompt | +| Chat: Read Aloud | None | Read a specific chat response using text-to-speech | +| Chat: Stop Reading Aloud | `Escape` | Stop text-to-speech playback | + +### Custom Keybindings for Voice + +You can assign your own shortcuts for voice commands. Open the Keyboard Shortcuts editor (`Ctrl+K Ctrl+S`) and search for "voice" or "dictation". Example custom keybinding in `keybindings.json`: + +```json +[ + { + "key": "ctrl+u", + "command": "workbench.action.chat.startVoiceChat", + "when": "!voiceChatInProgress" + }, + { + "key": "ctrl+u", + "command": "workbench.action.chat.stopListeningAndSubmit", + "when": "voiceChatInProgress" + }, + { + "key": "ctrl+d", + "command": "workbench.action.editorDictation.start", + "when": "!editorDictation.inProgress" + }, + { + "key": "ctrl+d", + "command": "workbench.action.editorDictation.stop", + "when": "editorDictation.inProgress" + } +] +``` + +The `when` clauses ensure the same key toggles the feature on and off. + +### Supported Platforms + +| Platform | Architecture | +| -------- | ------------ | +| Windows | x64, ARM | +| macOS | x64 (Intel), ARM (Apple Silicon) | +| Linux | x64, ARM32, ARM64 (Ubuntu 20.04/22.04/24.04, Debian 11/12, RHEL 8, CentOS 8) | + +On Linux, the extension requires the ALSA shared library (`libasound`). Install it with `sudo apt install libasound2` on Debian/Ubuntu if it is not already present. + + +--- + +## 19. Markdown Authoring in VS Code + +You write Markdown in nearly every challenge of this workshop -- issue descriptions, pull request bodies, README updates, and agent files. VS Code has built-in tools and extensions that make Markdown authoring faster, catch formatting mistakes before you commit, and work well with screen readers and keyboard navigation. + +### Markdown Preview + +VS Code includes a live Markdown preview so you can see rendered output alongside your source. + +- **Side-by-side preview:** Press `Ctrl+K V` (Mac: `Cmd+K V`) to open a preview pane to the right of your editor. As you type, the preview updates automatically. +- **Full preview:** Press `Ctrl+Shift+V` (Mac: `Cmd+Shift+V`) to replace the editor tab with a rendered preview. Press the same shortcut again to return to the source. +- **Scroll sync:** The preview scrolls in sync with the editor by default. If you scroll in the source, the preview follows. + +> **Screen reader tip:** The preview pane renders HTML, so your screen reader announces headings, links, and list items using their semantic roles. This is a quick way to verify that your heading hierarchy is correct -- listen for "heading level 2," "heading level 3," and so on. Switch between the editor and preview panes with `Ctrl+1` and `Ctrl+2`. + +### The markdownlint Extension + +The **markdownlint** extension (identifier: `DavidAnson.vscode-markdownlint`) catches common Markdown mistakes as you type, the same way a spell checker catches typos. + +**What it catches:** + +- Heading levels that skip (jumping from `##` to `####`) +- Missing blank lines before and after headings, lists, and code blocks +- Inconsistent list markers (mixing `-` and `*`) +- Trailing spaces and hard tabs +- Bare URLs that should be wrapped in angle brackets or link syntax + +**Installing markdownlint:** + +1. Open Extensions: `Ctrl+Shift+X` (Mac: `Cmd+Shift+X`) +2. Search for **markdownlint** +3. Install the one by **David Anson** + +Once installed, problems appear as wavy underlines in the editor and as entries in the Problems panel (`Ctrl+Shift+M`). Each entry includes the rule number (such as MD022 or MD032) and a short description. + +**Configuring rules:** If a rule does not fit your project, create a `.markdownlint.json` file in the repository root: + +```json +{ + "MD013": false, + "MD033": false +} +``` + +This disables the line-length rule (MD013) and the inline-HTML rule (MD033). The extension picks up the file automatically. + +> **Screen reader tip:** Press `Ctrl+Shift+M` to open the Problems panel, then use `Up` and `Down` arrows to browse warnings. Press `Enter` on a warning to jump directly to the offending line in the editor. Your screen reader announces the rule number and description for each item. + +### Outline View for Headings + +The Outline view shows the heading structure of your Markdown file as a navigable tree -- think of it as a table of contents you can jump through. + +- **Open Outline:** Press `Ctrl+Shift+O` (Mac: `Cmd+Shift+O`) to open the Go to Symbol quick-pick, which lists every heading in the file. Type to filter, then press `Enter` to jump. +- **Outline panel:** The Outline view also appears in the Explorer sidebar. Press `Ctrl+Shift+E` to open Explorer, then `Tab` until you reach the Outline section. +- **Breadcrumbs:** The breadcrumb bar at the top of the editor shows your current heading context. Press `Ctrl+Shift+.` to focus breadcrumbs and navigate between headings. + +> **Screen reader tip:** The Go to Symbol list (`Ctrl+Shift+O`) announces each heading with its level -- for example, "H2 Installation" or "H3 Configuring rules." This is the fastest way to verify your document structure without scrolling through the entire file. + +### Copilot Markdown Assistance + +If you have GitHub Copilot enabled (see [Chapter 16](16-github-copilot.md)), it can help with Markdown authoring directly in the editor. + +- **Generate tables:** Type a comment like `` and Copilot suggests a formatted Markdown table. Press `Tab` to accept. +- **Fix formatting:** Select a block of text, open inline chat (`Ctrl+I`), and type "fix the Markdown formatting." Copilot restructures headings, adds missing blank lines, and corrects list indentation. +- **Suggest alt text:** Select an image link like `![](screenshot.png)`, open inline chat, and ask "suggest alt text for this image." Copilot proposes a description based on the filename and surrounding context. +- **Complete link syntax:** Start typing `[link text](` and Copilot often autocompletes the URL from your recent files or repository structure. + +These features save time when you are writing issue descriptions or pull request bodies during the workshop challenges. + +### Markdown Keyboard Shortcuts + +| Action | Windows / Linux | macOS | +| ------ | --------------- | ----- | +| Toggle Markdown preview (full) | `Ctrl+Shift+V` | `Cmd+Shift+V` | +| Open preview to the side | `Ctrl+K V` | `Cmd+K V` | +| Go to heading (symbol) | `Ctrl+Shift+O` | `Cmd+Shift+O` | +| Open Problems panel | `Ctrl+Shift+M` | `Cmd+Shift+M` | +| Toggle bold | `Ctrl+B` | `Cmd+B` | +| Toggle italic | `Ctrl+I` (when text is selected) | `Cmd+I` (when text is selected) | +| Open inline chat (Copilot) | `Ctrl+I` (when nothing is selected) | `Cmd+I` | +| Focus breadcrumbs | `Ctrl+Shift+.` | `Cmd+Shift+.` | + +### Why This Matters for the Workshop + +Students write Markdown in every single challenge -- from the very first issue you file in [Chapter 5](05-working-with-issues.md) to the agent file you create in [Chapter 20](20-build-your-agent.md). Markdown is also how you write pull request descriptions ([Chapter 6](06-working-with-pull-requests.md)) and README files. + +Getting comfortable with preview, linting, and navigation tools means fewer formatting mistakes, faster editing, and more confidence that your content looks right before you submit it. The markdownlint extension is especially valuable because it catches problems that are invisible when you are reading raw Markdown in a screen reader -- like a skipped heading level or a missing blank line that breaks a list. + +Install markdownlint now. Open a Markdown file. Press `Ctrl+Shift+M` to check for warnings. Fix one. That small habit pays off in every challenge ahead. + + +## If You Get Stuck + +| Problem | What to do | +|---|---| +| Screen Reader Mode not working | Press `Shift+Alt+F1` or open Command Palette > "Toggle Screen Reader Mode". Restart VS Code if needed. | +| Terminal does not announce output | Press `Ctrl+Shift+A` to open Accessible Terminal Buffer. Or use **Accessible View** (`Shift+Alt+F2`) while the terminal is focused. | +| Copilot Chat not responding | Verify you are signed in to GitHub (check Accounts button in Activity Bar). Check that Copilot is enabled in your account settings. | +| Problems panel shows no errors | Open a file first. Some linters only activate when the file type is recognized. Check that extensions (e.g., markdownlint) are installed and enabled. | +| Keyboard shortcut does not work | The shortcut may be remapped. Open Keyboard Shortcuts (`Ctrl+K Ctrl+S`) and search for the action to find or reset the binding. | +| Accessibility Signals not playing | Go to Settings > search "accessibility signal" > verify the signals you want are set to "on" or "auto". Check your system audio volume. | +| Everything else | Open Command Palette > "Developer: Toggle Developer Tools" to check the console for errors. Post what you find on your challenge issue. | + +--- + +*Next: [Chapter 13: How Git Works](13-how-git-works.md)* +*Back: [Chapter 11: VS Code Interface](11-vscode-interface.md)* +*Related appendices: [Appendix G: VS Code Reference](appendix-g-vscode-reference.md)* + diff --git a/admin/qa-bundle/docs/13-how-git-works.md b/admin/qa-bundle/docs/13-how-git-works.md new file mode 100644 index 0000000..af2ec51 --- /dev/null +++ b/admin/qa-bundle/docs/13-how-git-works.md @@ -0,0 +1,537 @@ +# How Git Works: The Mental Model + +> **Related appendices:** [Appendix E: Advanced Git](appendix-e-advanced-git.md) | [Appendix D: Git Authentication](appendix-d-git-authentication.md) | [Appendix F: Git Security](appendix-f-git-security.md) +> **Authoritative sources:** [Git SCM: Git Basics](https://git-scm.com/book/en/v2/Getting-Started-What-is-Git%3F) | [Git SCM: Branching in a Nutshell](https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell) | [GitHub Docs: About Git](https://docs.github.com/en/get-started/using-git/about-git) + + +> **Day 2, Block 1 Material** +> +> Before you start running Git commands, you need a mental model of what Git actually does. This chapter builds that model from the ground up: what a commit is, what a branch is, how local and remote repositories relate, and why merge conflicts happen. Every operation in [Chapter 14](14-git-in-practice.md) will make more sense after reading this. + +## Table of Contents + +1. [Why a Mental Model Matters](#1-why-a-mental-model-matters) +2. [The Three Areas: Working Directory, Staging Area, Repository](#2-the-three-areas-working-directory-staging-area-repository) +3. [What Is a Commit?](#3-what-is-a-commit) +4. [What Is a Branch?](#4-what-is-a-branch) +5. [Local vs Remote](#5-local-vs-remote) +6. [Push, Pull, and Fetch](#6-push-pull-and-fetch) +7. [Why Merge Conflicts Happen](#7-why-merge-conflicts-happen) +8. [The Git Timeline](#8-the-git-timeline) +9. [Putting It All Together](#9-putting-it-all-together) +10. [If You Get Stuck](#10-if-you-get-stuck) + +--- + +> **Challenges 10-16** all depend on the mental model built in this chapter. Understanding the three areas, branches, and push/pull makes every Day 2 Git command predictable. + +## 1. Why a Mental Model Matters + +On Day 1, you edited files on GitHub.com using the web editor. GitHub handled Git for you behind the scenes -- creating commits, managing branches, and tracking changes. You did not need to think about how it worked because the web interface made it invisible. + +On Day 2, you will do the same operations locally: clone a repository to your computer, create branches, make commits, and push changes back to GitHub. The commands themselves are not hard. But without understanding what they do, you will hit a wall the first time something goes wrong -- and you will not know how to fix it. + +This chapter gives you that understanding. It is not a list of commands (that is [Chapter 14](14-git-in-practice.md)). It is the mental model that makes the commands make sense. + +> **Authoritative source:** The concepts in this chapter are grounded in the [Pro Git book](https://git-scm.com/book/en/v2) by Scott Chacon and Ben Straub, which is the official Git documentation's recommended resource. It is free to read online. + +--- + +## 2. The Three Areas: Working Directory, Staging Area, Repository + +Git organizes your work into three areas. Understanding these three areas is the single most important concept in this chapter. + +### Working directory + +The working directory is the folder on your computer where the files live. When you open a project in VS Code, everything you see in the file explorer is the working directory. These are real files on your disk that you can edit, rename, and delete. + +When you change a file in the working directory, Git notices. But Git does not automatically record the change. You have to tell Git which changes you want to keep. + +### Staging area (also called the index) + +The staging area is a holding zone. When you are happy with a change in the working directory, you add it to the staging area. This is like saying: "I want this change to be part of my next save point." + +You can add some files to the staging area and leave others out. This lets you make a commit (save point) that includes only the changes that belong together. + +### Repository (the .git folder) + +The repository is Git's permanent record. When you commit, Git takes everything in the staging area and stores it as a snapshot -- a permanent record of what those files looked like at that moment. The repository is stored in a hidden `.git` folder inside your project directory. + +### How the three areas connect + +The flow is always the same: + +1. **Edit** files in the working directory +2. **Stage** the changes you want to keep (add to the staging area) +3. **Commit** the staged changes (save to the repository) + +In Git commands, this looks like: + +```text +edit a file --> git add file.md --> git commit -m "description" +(working directory) (staging area) (repository) +``` + +> **Screen reader note:** Many visual Git tutorials use diagrams with arrows to show this flow. The text description above and the three-step sequence are the same information without requiring a visual representation. + +### An analogy: packing a box + +Think of it like packing a box to mail: + +- The **working directory** is your desk with papers and items scattered on it +- The **staging area** is the open box on the floor -- you put items into it as you decide what to ship +- The **commit** is sealing the box, labeling it, and putting it on the shelf -- once sealed, its contents are recorded permanently + +You can put items in and take them out of the box (stage and unstage) as many times as you want before sealing it (committing). + +### Learning Cards: The Three Areas + +
    +Screen reader users + +- Run `git status` in the terminal (`Ctrl+\``) -- it announces which files are in each area (working directory, staging, committed) with clear labels +- In VS Code Source Control (`Ctrl+Shift+G`), files are grouped under "Changes" (working directory) and "Staged Changes" (staging area) -- navigate with arrow keys +- Press `Enter` on any file in the Source Control panel to hear the diff -- added and removed lines are announced with change-type prefixes + +
    + +
    +Low vision users + +- In Source Control (`Ctrl+Shift+G`), staged files appear under a separate "Staged Changes" heading with a green `+` icon; unstaged files are under "Changes" with an orange `M` icon +- Use `Ctrl+=` to increase editor font size if the Source Control file list is hard to read at default zoom +- The gutter indicator (colored bar on the left edge of the editor) shows green for added lines and blue for modified lines + +
    + +
    +Sighted users + +- The Source Control badge on the Activity Bar shows a number indicating how many files have changes -- click it to see the full list +- Look for letter badges next to filenames: `M` (modified), `U` (untracked), `A` (added to staging), `D` (deleted) +- The inline gutter colors in the editor margin (green = added, blue = modified, red = deleted) show changes at a glance without opening Source Control + +
    + +--- + +## 3. What Is a Commit? + +A commit is a snapshot of your project at a specific moment in time. It is not a diff (a list of changes). It records the complete state of every file in the staging area when the commit was made. + +### What a commit contains + +Every commit has four parts: + +| Part | What it is | Example | +|---|---|---| +| **Snapshot** | The complete state of all staged files | All the files as they were when you committed | +| **Message** | A human-readable description of the change | "Fix broken link in setup guide" | +| **Author** | Who made the commit (name and email) | Jane Developer, jane@example.com | +| **Parent pointer** | Which commit came before this one | A reference to the previous commit's ID | + +### Commit IDs (hashes) + +Every commit gets a unique identifier -- a 40-character string called a SHA hash. It looks like this: + +```text +a1b2c3d4e5f6789012345678901234567890abcd +``` + +In practice, you usually see only the first 7 characters: `a1b2c3d`. This short form is enough to uniquely identify a commit in most repositories. + +You do not need to memorize these. Git commands accept both the full hash and the short form. + +### Commits are permanent (mostly) + +Once a commit is made, it is part of the repository's history. You can make new commits that undo the changes, but the original commit still exists in the timeline. This is what makes Git safe: you can always go back. + +> **The Day 1 connection:** When you edited a file on GitHub.com and clicked "Commit changes," GitHub created a commit for you. It did the stage-and-commit steps in a single action. On Day 2, you will do these steps separately, which gives you more control. + +### Learning Cards: Commits + +
    +Screen reader users + +- After committing, run `git log --oneline -5` in the terminal to hear the last 5 commit hashes and messages read aloud +- In VS Code, press `Ctrl+Shift+G` then navigate to the commit message input box -- your screen reader announces "Message" -- type your description and press `Ctrl+Enter` to commit +- The 7-character short hash (e.g., `a1b2c3d`) is what Git commands accept -- you do not need the full 40 characters + +
    + +
    +Low vision users + +- The Source Control commit input box is at the top of the Source Control panel -- increase panel width by dragging the panel edge if the text is truncated +- After committing, the file count badge on the Source Control icon drops to zero, confirming the commit succeeded +- Use Timeline view (`Ctrl+Shift+P` then "Focus on Timeline View") to see a chronological list of commits for the current file + +
    + +
    +Sighted users + +- The commit message input box sits at the top of the Source Control panel with a checkmark button to commit +- After committing, the "Staged Changes" section disappears and the Activity Bar badge number decreases +- Hover over any commit in the Timeline view to see the full message, author, and timestamp in a tooltip + +
    + +--- + +## 4. What Is a Branch? + +> **See also:** [Chapter 14: Git in Practice](14-git-in-practice.md) shows how to create and switch branches hands-on in VS Code. + +A branch is a name that points to a specific commit. That is the entire definition. A branch is not a copy of your files. It is not a separate folder. It is a pointer -- a label stuck on one specific commit. + +### The default branch: main + +Every repository has a default branch, usually called `main`. When you clone a repository, Git checks out the `main` branch, which means it loads the files from the commit that `main` points to into your working directory. + +### Creating a branch + +When you create a new branch, Git creates a new pointer that starts at the same commit you are currently on. Both branches point to the same commit. No files are copied. + +```text +Before creating a branch: + main --> commit C + +After creating a branch called "fix/typo": + main --> commit C + fix/typo --> commit C (same commit, two names) +``` + +### Making commits on a branch + +When you make a new commit while on the `fix/typo` branch, the `fix/typo` pointer moves forward to the new commit. The `main` pointer stays where it was. + +```text + main --> commit C + fix/typo --> commit D --> commit C +``` + +Now `fix/typo` is one commit ahead of `main`. The files on `main` have not changed. The files on `fix/typo` include your new edit. + +### HEAD: which branch are you on? + +Git uses a special pointer called `HEAD` to track which branch you are currently working on. When you switch branches (checkout), Git moves `HEAD` to point to the new branch and updates the files in your working directory to match. + +> **The Day 1 connection:** On Day 1, you created a `learn/[username]` branch on GitHub.com. That branch was a pointer to a specific commit on the repository. When you edited files on that branch, new commits moved the pointer forward. The `main` branch stayed unchanged until your pull request was merged. + +### Learning Cards: Branches + +
    +Screen reader users + +- Press `Ctrl+Shift+G` then `Tab` to reach the branch name in the Source Control panel -- your screen reader announces the current branch +- The Status Bar at the bottom of VS Code shows the current branch name -- navigate to it with `F6` to cycle through Status Bar items +- To switch branches, press `Ctrl+Shift+P` then type "Git: Checkout to" and arrow through the branch list + +
    + +
    +Low vision users + +- The current branch name appears in the bottom-left of the Status Bar -- click it to see a dropdown of all branches +- Branch names in the Status Bar use the same font size as the rest of the bar; zoom the entire window with `Ctrl+=` if it is too small +- In the Source Control panel, the branch name is shown above the commit input -- verify it before committing + +
    + +
    +Sighted users + +- Look at the bottom-left corner of VS Code for the branch icon and name (e.g., a git-branch icon followed by `main`) +- Click the branch name to open a picker showing all local and remote branches -- select one to switch +- The branch icon changes to a sync icon with arrows when your branch is ahead of or behind the remote + +
    + +--- + +## 5. Local vs Remote + +> **See also:** [Appendix D: Git Authentication](appendix-d-git-authentication.md) covers how to set up credentials so push and pull work without password prompts. + +So far, we have talked about one repository. In practice, you work with two copies of the same repository. + +### The remote repository + +The remote repository is the one on GitHub.com. It is called `origin` by convention. When you see a repository URL like `github.com/Community-Access/git-going-with-github`, that is the remote. + +The remote is the shared copy. Everyone on the team can see it. Pull requests happen here. Issues live here. It is the source of truth for the project. + +### The local repository + +The local repository is the copy on your computer. When you run `git clone`, Git downloads the entire repository -- all files, all branches, all history -- to your machine. You now have a complete, independent copy. + +You can make commits locally without any internet connection. Your commits are saved in your local repository. The remote does not know about them until you push. + +### How local and remote stay in sync + +| Operation | Direction | What it does | +|---|---|---| +| `git clone` | Remote to local | Creates a new local copy of the entire remote repository | +| `git push` | Local to remote | Sends your local commits to the remote repository | +| `git pull` | Remote to local | Downloads new commits from the remote and merges them into your branch | +| `git fetch` | Remote to local | Downloads new commits from the remote but does not merge them | + +### The two-copy model + +```text +Your computer (local) GitHub.com (remote / origin) ++-------------------+ +-------------------+ +| working directory | git push | | +| staging area | --------> | shared branches | +| repository (.git) | <-------- | pull requests | ++-------------------+ git pull | issues | + +-------------------+ +``` + +> **Screen reader note:** The text diagram above shows two boxes side by side connected by arrows. The left box is labeled "Your computer (local)" and contains working directory, staging area, and repository. The right box is labeled "GitHub.com (remote / origin)" and contains shared branches, pull requests, and issues. Arrows show `git push` going from left to right and `git pull` going from right to left. + +### Learning Cards: Local vs Remote + +
    +Screen reader users + +- Run `git remote -v` in the terminal to hear which remote URLs are configured -- typically `origin` pointing to your GitHub repository +- After `git push`, your screen reader announces the output including the branch name and commit count sent -- listen for "Everything up-to-date" if nothing new to push +- Run `git status` to hear whether your local branch is ahead of, behind, or in sync with the remote tracking branch + +
    + +
    +Low vision users + +- The Status Bar sync indicator (bottom-left, next to the branch name) shows up/down arrow counts: up-arrows = commits to push, down-arrows = commits to pull +- Click the sync icon in the Status Bar to push and pull in one action -- the arrows disappear when local and remote are in sync +- The Source Control panel heading shows the repository name and branch so you can confirm which remote you are working with + +
    + +
    +Sighted users + +- Look for the cloud icon or sync arrows next to the branch name in the Status Bar to see push/pull status at a glance +- A number next to the up arrow means you have unpushed commits; next to the down arrow means the remote has commits you have not pulled +- The Source Control panel shows a "Publish Branch" button when you have a local branch that does not yet exist on the remote + +
    + +--- + +## 6. Push, Pull, and Fetch + +These three operations keep your local and remote repositories synchronized. + +### Push: share your work + +`git push` sends your local commits to the remote. After pushing, anyone who looks at the repository on GitHub.com will see your changes. + +Push only sends commits on the current branch. If you are on the `fix/typo` branch and push, only `fix/typo` commits go to the remote. Other branches are untouched. + +```bash +git push origin fix/typo +``` + +If this is the first push for a new branch, use: + +```bash +git push -u origin fix/typo +``` + +The `-u` flag sets up tracking so that future pushes from this branch go to the right place without specifying the remote and branch name. + +### Pull: get other people's work + +`git pull` downloads new commits from the remote and immediately merges them into your current branch. This is how you get changes that other people (or you on another computer) have pushed. + +```bash +git pull origin main +``` + +Pull is actually two operations combined: fetch (download) + merge (integrate). Most of the time this works automatically. When it cannot merge automatically, you get a merge conflict (see Section 7). + +### Fetch: check for updates without merging + +`git fetch` downloads new commits from the remote but does not change your working directory or current branch. It just updates your local knowledge of what the remote looks like. + +This is useful when you want to see if there are new changes before deciding to merge them. + +```bash +git fetch origin +``` + +After fetching, you can compare your branch with the remote's version: + +```bash +git log main..origin/main --oneline +``` + +This shows you what commits exist on the remote's `main` that you do not have locally. + +--- + +## 7. Why Merge Conflicts Happen + +A merge conflict happens when Git cannot automatically combine two sets of changes. This is not an error. It is Git asking you for help. + +### When conflicts occur + +Conflicts happen when two branches modify the same lines in the same file. Git knows how to merge changes to different files, and even different parts of the same file. But when two branches change the same line differently, Git cannot decide which version to keep. + +### What a conflict looks like + +When a conflict occurs, Git marks the conflicting section in the file with special markers: + +```text +<<<<<<< HEAD +This is the text from your current branch. +======= +This is the text from the branch you are merging in. +>>>>>>> fix/typo +``` + +| Marker | Meaning | +|---|---| +| `<<<<<<< HEAD` | Start of your current branch's version | +| `=======` | Divider between the two versions | +| `>>>>>>> fix/typo` | End of the incoming branch's version | + +### How to resolve a conflict + +1. Open the file with the conflict markers +2. Read both versions and decide which text to keep (or write a new version that combines both) +3. Delete the conflict markers (`<<<<<<<`, `=======`, `>>>>>>>`) +4. Save the file +5. Stage and commit the resolved file + +> **The Day 1 connection:** In [Chapter 7](07-merge-conflicts.md), you resolved a merge conflict on GitHub.com using the web editor. The same markers appeared there. On Day 2, you will resolve conflicts in VS Code, where the editor highlights the markers and offers buttons to accept one side or the other. + +### Why conflicts are normal + +Conflicts are not mistakes. They happen in every project where more than one person works at the same time. The fact that Git stops and asks is a safety feature -- it prevents data loss by never silently choosing one version over another. + +### Learning Cards: Merge Conflicts + +
    +Screen reader users + +- When a conflict occurs, VS Code announces "Merge conflict" and the file appears in Source Control under "Merge Changes" -- navigate with arrow keys +- Use `F7` in the diff viewer to step through conflict hunks; each hunk announces the line range and both versions of the conflicting text +- After resolving, stage the file (`Ctrl+Shift+G`, navigate to the file, press `+`) then commit to complete the merge + +
    + +
    +Low vision users + +- Conflict markers (`<<<<<<<`, `=======`, `>>>>>>>`) appear as highlighted blocks in the editor -- look for colored backgrounds (green for current, blue for incoming) +- VS Code places "Accept Current Change", "Accept Incoming Change", and "Accept Both" buttons inline above each conflict -- they are large enough to click at high zoom +- Increase editor zoom with `Ctrl+=` to make the conflict marker labels easier to read + +
    + +
    +Sighted users + +- Conflict regions are highlighted with distinct background colors: green for your changes (Current), blue for incoming changes +- Click "Accept Current Change", "Accept Incoming Change", or "Accept Both Changes" above each conflict block to resolve with one click +- The Source Control badge shows a merge icon when you are in a merge state -- commit after all conflicts are resolved to complete the merge + +
    + +--- + +## 8. The Git Timeline + +Every commit has a parent pointer (except the very first commit). This creates a chain -- a timeline of the project's history. + +### Reading the timeline + +The timeline reads backward: the most recent commit points to the one before it, which points to the one before that, all the way back to the first commit. + +```text +first commit <-- second commit <-- third commit <-- fourth commit (main) +``` + +When you run `git log`, Git follows these pointers from the current commit backward and shows you each commit's message, author, date, and hash. + +### Branching creates parallel timelines + +When two branches diverge (both have commits that the other does not), the timeline splits into two parallel paths: + +```text + +-- commit E -- commit F (fix/typo) + / +commit A -- commit B -- commit C -- commit D (main) +``` + +Both branches share commits A and B (their common history). After the split point, each branch has its own commits. + +### Merging reconnects timelines + +When you merge `fix/typo` into `main`, Git creates a new merge commit that has two parents: the latest commit on `main` and the latest commit on `fix/typo`. The two timelines join back together. + +```text + +-- commit E -- commit F (fix/typo) + / \ +commit A -- B -- C -- D -------- merge commit G (main) +``` + +After merging, `main` contains all the changes from both branches. + +> **Screen reader note:** The text diagrams in this section show commit history as a horizontal chain reading left to right. Branch points are shown with `+--` and merge points are shown with `\`. The key information is: branches diverge from a common ancestor commit and merge back together with a merge commit. + +--- + +## 9. Putting It All Together + +Here is the complete workflow that you will practice in [Chapter 14](14-git-in-practice.md), translated through the mental model: + +| Step | What you do | What Git does | +|---|---|---| +| Clone the repo | `git clone URL` | Copies the entire remote repository to your computer | +| Create a branch | `git checkout -b fix/typo` | Creates a new pointer at your current commit and switches HEAD to it | +| Edit a file | Open and modify the file | Git detects the change in the working directory | +| Stage the change | `git add file.md` | Moves the change from the working directory to the staging area | +| Commit | `git commit -m "Fix typo"` | Takes a snapshot of the staging area and stores it in the repository | +| Push | `git push -u origin fix/typo` | Sends your commit to the remote repository on GitHub | +| Open a PR | On GitHub.com | Proposes merging your branch into main | +| Merge | PR merged on GitHub.com | Creates a merge commit that joins your branch back into main | +| Pull | `git pull origin main` | Downloads the merge commit to your local copy | + +Everything in this table maps directly to the three areas (Section 2), the two copies (Section 5), and the timeline (Section 8). + +### Quick mental model checklist + +Before running a Git command, ask yourself: + +- **Where am I?** Which branch is HEAD on? (`git status` tells you) +- **What has changed?** Are there modifications in the working directory? Staged changes? (`git status` tells you) +- **Which direction?** Am I pushing (local to remote) or pulling (remote to local)? +- **What could conflict?** Has anyone else changed the same files on the same branch? + +If you can answer these four questions, you can troubleshoot almost any Git situation. + +--- + +## 10. If You Get Stuck + +| Situation | What to do | +|---|---| +| "I do not understand which area my file is in" | Run `git status`. It lists files in each area with clear labels (modified, staged, untracked). | +| "I committed to the wrong branch" | Do not panic. The commit is safe. See [Appendix E](appendix-e-advanced-git.md) for how to move commits between branches. | +| "I pushed something I did not mean to push" | The remote now has your commit. You can revert it with a new commit. Never force-push on a shared branch without coordination. | +| "I have merge conflict markers and do not know what to do" | Go to [Chapter 7](07-merge-conflicts.md) for step-by-step resolution. The key rule: delete all markers, keep the text you want, stage, and commit. | +| "Git says my branch is behind the remote" | Run `git pull` to download the new commits. If there are conflicts, resolve them. | +| "I do not understand the error message" | Copy the exact error text and search for it. The [Pro Git book troubleshooting section](https://git-scm.com/book/en/v2) and [Stack Overflow](https://stackoverflow.com/questions/tagged/git) both have clear explanations. | + +--- + +*Next: [Chapter 14: Git in Practice](14-git-in-practice.md)* +*Back: [Chapter 12: VS Code Accessibility](12-vscode-accessibility.md)* +*Related appendices: [Appendix E: Advanced Git](appendix-e-advanced-git.md) | [Appendix D: Git Authentication](appendix-d-git-authentication.md)* + diff --git a/admin/qa-bundle/docs/14-git-in-practice.md b/admin/qa-bundle/docs/14-git-in-practice.md new file mode 100644 index 0000000..81c62f4 --- /dev/null +++ b/admin/qa-bundle/docs/14-git-in-practice.md @@ -0,0 +1,2120 @@ +# Git & Source Control in VS Code +> +> **Listen to Episode 12:** [Git and Source Control in VS Code](../admin/PODCASTS.md) - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. + +> **Related appendices:** [Appendix E: Advanced Git](appendix-e-advanced-git.md) | [Appendix D: Git Authentication](appendix-d-git-authentication.md) | [Appendix H: GitHub Desktop](appendix-h-github-desktop.md) +> **Authoritative sources:** [VS Code Docs: Source Control](https://code.visualstudio.com/docs/sourcecontrol/overview) | [GitHub Docs: Using Git](https://docs.github.com/en/get-started/using-git) + + +## Managing Repositories, Branches, and Changes Accessibly + +> **Day 2, Block 1-2 Material** +> +> This guide covers all Git operations in VS Code: cloning repositories, navigating the Source Control panel with screen readers, branch management, staging changes (including individual lines), push/pull operations, viewing file history with Timeline, resolving merge conflicts, and stash management. +> +> **Prerequisites:** [VS Code Setup & Accessibility Basics](11-vscode-interface.md), [Working with Pull Requests](06-working-with-pull-requests.md), [Merge Conflicts](07-merge-conflicts.md) +> +> **Mac keyboard shortcuts:** Throughout this chapter, all `Ctrl+` shortcuts use `Cmd+` on Mac, and `Alt+` shortcuts use `Option+`. Common equivalents: `Ctrl+Shift+G` → `Cmd+Shift+G`, `Ctrl+Shift+P` → `Cmd+Shift+P`, `Ctrl+Enter` → `Cmd+Enter`, `Ctrl+S` → `Cmd+S`. + + +## Workshop Recommendation (Chapter 14 / Challenge 10) + +Chapter 14 is the first **local Git workflow chapter** with hands-on repository management. It supports Challenge 10: Go Local. + +- **Challenge count:** 3 +- **Time per challenge:** under 10 minutes each +- **Evidence:** PR metadata, branch names, and committed changes +- **Pattern:** clone, branch, edit, commit, push, PR + +### Challenge 10 Practice Set + +1. **Clone your Learning Room repository** - clone your private Learning Room repo to your local machine using VS Code. +2. **Create a branch and make one commit** - check out (or create) your `learn/` branch, edit a file, stage, write a clear commit message, and commit locally. +3. **Push and open a linked PR** - push your branch and open a PR in your Learning Room repo that references your Challenge 10 or Day 2 PR issue. + +### Practice 10.1 Step-by-Step: Clone Your Learning Room Repository + +**Goal:** Get a local copy of your Learning Room repository on your machine using VS Code. + +**Where you are working:** VS Code desktop (or github.dev if you cannot install desktop VS Code). + +Your Learning Room repo is the same repo you have been working in all of Day 1 -- the private copy of `learning-room-template` that GitHub Classroom created for you. Cloning it locally lets you practice the full local Git workflow on a codebase you already know. + +Do **not** clone `Community-Access/learning-room-template` for this challenge. That template is maintained by facilitators. Clone your own private Learning Room repository, the one whose URL looks like `https://github.com//learning-room-.git`. + +You do **not** need a GitHub organization or organization-level permissions to complete this workflow. If GitHub asks for authentication, sign in with your own GitHub account. If GitHub says you do not have access to the repo, confirm that you are using your private Learning Room URL and ask a facilitator for help. + +1. Open VS Code. If no folder is open, you should see the Welcome tab. +2. Open the Command Palette: `Ctrl+Shift+P` (Mac: `Cmd+Shift+P`). +3. Type `git clone` and select **Git: Clone**. +4. VS Code asks for a repository URL. Paste your Learning Room repo URL (it looks like `https://github.com//learning-room-.git`). You can copy this from the green **Code** button on your repo's GitHub page. +5. Press `Enter`. +6. A file browser dialog opens asking where to save the clone. Choose a folder you can find easily (for example, `Documents` or `Desktop`). Press **Select as Repository Destination**. +7. VS Code clones the repository. When it finishes, a notification appears asking "Would you like to open the cloned repository?" Activate **Open**. +8. Verify the clone worked: press `Ctrl+Shift+E` (Mac: `Cmd+Shift+E`) to open Explorer. Your screen reader should announce the file tree with files like `README.md` and the `docs/` folder. + +**Screen reader tip:** After step 6, VS Code shows a progress notification. NVDA reads this automatically. If you hear nothing for 30 seconds, open the Command Palette and run `Notifications: Focus Notification Toast` to check status. + +**You are done when:** Your Learning Room repo folder is open in VS Code and you can see the `docs/` folder along with `README.md` in the Explorer panel. + +> **After cloning: check what branches exist.** A fresh clone only checks out the default branch (`main`), but the remote may have other branches you created earlier on GitHub.com (such as your `learn/` branch). Run `git branch -a` in the terminal (`` Ctrl+` ``) to see all branches -- local and remote: +> +> ```bash +> git branch -a +> ``` +> +> You will see output like: +> +> ```text +> * main +> remotes/origin/HEAD -> origin/main +> remotes/origin/main +> remotes/origin/learn/yourname +> ``` +> +> The `*` marks your current branch. Lines starting with `remotes/origin/` are branches on GitHub that you can check out locally with `git checkout learn/yourname` or `git switch learn/yourname`. + +### Practice 10.2 Step-by-Step: Create a Branch and Commit + +> **See also:** [Chapter 13: How Git Works](13-how-git-works.md) explains the three areas (working directory, staging, repository) that make commits meaningful. + +**Goal:** Check out (or create) a properly named branch, edit a file, stage the change, and commit with a clear message. + +**Where you are working:** VS Code with your cloned Learning Room repository open. + +1. Open the Command Palette: `Ctrl+Shift+P` (Mac: `Cmd+Shift+P`). +2. If your `learn/` branch already exists on the remote (because you created it during Day 1), type `git checkout` and select **Git: Checkout to...**, then pick `learn/`. If the branch does not exist yet, type `git create branch` and select **Git: Create Branch...** and enter `learn/`. +3. The status bar at the bottom of VS Code now shows your branch name instead of `main`. Your screen reader announces the branch name when you focus the status bar. +4. Open the Explorer (`Ctrl+Shift+E`) and navigate to the `docs/` folder. Open any file mentioned in your Challenge 10 issue (for example, `docs/welcome.md`). +5. Make one small, meaningful edit. For example, add a new sentence, fix a typo, or improve a description. Save the file with `Ctrl+S` (Mac: `Cmd+S`). +6. Open the Source Control panel: `Ctrl+Shift+G` (Mac: `Cmd+Shift+G`). Your screen reader announces "Source Control" and shows your changed file under "Changes." +7. Navigate to your changed file in the Changes list. Press `Enter` or activate the `+` (Stage Changes) button next to the filename. The file moves from "Changes" to "Staged Changes." +8. Move focus to the **Message** input box at the top of the Source Control panel. Type a clear commit message, for example: `docs: improve welcome.md introduction` +9. Press `Ctrl+Enter` (Mac: `Cmd+Enter`) to commit. The staged changes disappear, which means your commit succeeded. + +**Screen reader tip:** In the Source Control panel, use arrow keys to navigate between changed files. Each file announces its name and change status (modified, added, deleted). The `+` button is announced as "Stage Changes" when you Tab to it. + +**You are done when:** Your commit appears in the Source Control panel's history (no more staged or unstaged changes visible) and the status bar still shows your branch name. + +### Practice 10.3 Step-by-Step: Push and Open a Linked PR + +**Goal:** Push your branch to GitHub and open a PR in your Learning Room repo that references your challenge issue. + +**Where you are working:** VS Code (for the push) and GitHub.com (for the PR). + +1. Open the Command Palette: `Ctrl+Shift+P` (Mac: `Cmd+Shift+P`). +2. Type `git push` and select **Git: Push**. If VS Code asks to publish the branch (because it is new), confirm by selecting **OK** or **Publish Branch**. +3. Wait for the push to complete. VS Code shows a progress notification. When done, the sync indicator in the status bar should show no pending changes. +4. Open your browser and navigate to your Learning Room repository on GitHub. +5. GitHub usually shows a yellow banner: "yourname recently pushed to learn/yourname." Activate the **Compare & pull request** button in that banner. +6. If you do not see the banner, activate the **Pull requests** tab, then activate **New pull request**. Set the base branch to `main` and the compare branch to your `learn/` branch. +7. In the PR title, write a descriptive title (for example: "docs: improve welcome.md introduction"). +8. In the PR description, type `Closes #XX` (replace `XX` with your Challenge 10 or Day 2 PR issue number). Because the issue lives in the same repo as the PR, you only need the short `#XX` form. +9. Activate the **Create pull request** button. + +**Screen reader tip:** The "Compare & pull request" banner is a standard link element near the top of the repository page. If your screen reader does not find it, use the heading navigation to jump to the Pull Requests tab instead. + +**Same-repo linking:** Because your challenge issue and your PR live in the same repository, the short form `Closes #XX` is enough -- GitHub automatically resolves the issue number to a closure link. (If you ever open a PR in a different repo, you would use the full `Closes /#XX` form, which works exactly the same way.) + +**You are done when:** Your PR appears on the Pull requests tab of your Learning Room repo, shows your branch name, and the description contains the `Closes #XX` reference to your challenge issue. + +### Completing Challenge 10: Submit Your Evidence + +Open your **assigned Challenge 10 issue** in your Learning Room repo and post a completion comment: + +```text +Challenge 10 completed: +- Repository cloned: +- Branch name: learn/ +- Commit message: [your commit message] +- PR number: #[your PR number] +- PR links to issue: yes (Closes #XX in description) +``` + +Close your Challenge 10 issue when your branch is pushed and the PR is open. + +### Expected Outcomes + +- Student can clone a repository using VS Code Command Palette. +- Student can create or check out a named branch following the workshop naming convention. +- Student can navigate the Source Control panel, stage files, and commit with a descriptive message. +- Student can push a branch and open a PR with same-repo issue linking. + +### If You Get Stuck + +1. Command Palette does not open? Confirm you are in VS Code (not the browser) and press `Ctrl+Shift+P` (Mac: `Cmd+Shift+P`). +2. Source Control panel is empty? You may not have saved your file yet. Press `Ctrl+S` to save, then check again. +3. Push fails with authentication error? Open Command Palette, run `Git: Fetch` to test your connection. If it fails, run `GitHub: Sign In` from Command Palette. +4. Branch name wrong? Open Command Palette, run `Git: Rename Branch...` to fix it before pushing. +5. Cannot find the "Compare & pull request" banner on GitHub? Navigate to Pull requests tab and create the PR manually (step 6 above). +6. `Closes #XX` not linking? Make sure the format is exactly `Closes #XX` with a single space and no extra characters. The keyword is case-insensitive but must be one of `Closes`, `Fixes`, or `Resolves`. +7. Ask facilitator to verify your clone location, branch name, and help with one push. +8. Finished but not sure you did it right? Compare your work against the [Challenge 10 reference solution](solutions/solution-10-go-local.md). + +> **Continue learning:** The GitHub Skills course [Introduction to Git](https://github.com/skills/introduction-to-git) walks through commits, branches, and merges in an interactive, self-paced format. See [Appendix Z](appendix-z-github-skills.md) for the full catalog. + +### Learning Moment + +Local Git operations give you full control and immediate feedback. You can see your changes, review them, and fix mistakes before they reach GitHub. The clone-branch-edit-commit-push-PR cycle you just completed is the daily workflow of every open source contributor. And now your Copilot Chat has custom sci-fi loading phrases as a bonus. + +### Learning Pattern Used in This Chapter + +1. Clone once to get a local copy of the project. +2. Branch before editing (never work directly on `main`). +3. Make small, focused edits with clear commit messages. +4. Push and open a PR that links to an issue for traceability. +5. Verify each step before moving to the next. + +### About Learning Cards + +Throughout this chapter, each major operation includes **learning cards** - expandable sections showing how to accomplish the same task from multiple perspectives. Open the card that matches how you work: + +The following table describes each learning card type and who it is for. + +| Card | Who it is for | +| --- | --- | +| **Visual / mouse users** | Sighted users navigating with a mouse or trackpad | +| **Low vision users** | Users working with zoom (200%+), magnification, high contrast themes, or large cursors | +| **Screen reader users (NVDA / JAWS)** | Windows users navigating with NVDA or JAWS in Browse/Virtual mode | +| **Screen reader users (VoiceOver)** | macOS users navigating with VoiceOver | +| **GitHub.com web interface** | Browser-only workflow - no local tools required | +| **CLI (git / gh)** | Terminal commands for Git and GitHub CLI - predictable text output, scriptable | + +You do not need to read every card. Pick the one or two that match your setup and skip the rest. + + +## Table of Contents + +1. [Cloning a Repository in VS Code](#1-cloning-a-repository-in-vs-code) +2. [The Source Control Panel - Complete Walkthrough](#2-the-source-control-panel---complete-walkthrough) +3. [Branch Management](#3-branch-management) +4. [Staging Changes - Files, Lines, and Chunks](#4-staging-changes---files-lines-and-chunks) +5. [Committing with Screen Readers](#5-committing-with-screen-readers) +6. [Push and Pull Operations](#6-push-and-pull-operations) +7. [Discarding Changes](#7-discarding-changes) +8. [Timeline View - File History and Blame](#8-timeline-view---file-history-and-blame) +9. [Resolving Merge Conflicts in VS Code](#9-resolving-merge-conflicts-in-vs-code) +10. [Stash Management](#10-stash-management) +11. [Emergency Recovery - git reflog](#10b-emergency-recovery---git-reflog) +12. [Alternative Git Interfaces](#11-alternative-git-interfaces) + + +## 1. Cloning a Repository in VS Code + +### Tool Cards: Clone a Repository (Day 2) + +**VS Code Desktop (primary for Day 2):** +1. `Ctrl+Shift+P` > **Git: Clone** > paste the HTTPS URL > choose a folder > **Open**. + +**github.dev (web editor):** +No clone needed. Press `.` on any GitHub repository page to open it instantly. + +**GitHub Desktop:** +1. **File > Clone Repository** > paste URL or select from your account > **Clone**. + +**Git CLI (terminal):** +```bash +git clone https://github.com/owner/repo.git && cd repo +``` + +**GitHub CLI:** +```bash +gh repo clone owner/repo && cd repo +``` + +### Three ways to clone a repository + +### Method 1: Command Palette (Recommended for Screen Readers) + +1. Open Command Palette: `Ctrl+Shift+P` (Mac: `Cmd+Shift+P`) +2. Type "git clone" +3. Select "Git: Clone" +4. Paste the repository URL (example: `https://github.com/community-access/accessibility-agents.git`) +5. Press `Enter` +6. Choose a local folder where the repository should be cloned +7. VS Code asks: "Would you like to open the cloned repository?" - select "Open" + +#### Screen reader navigation + +- The Command Palette is a searchable list - type to filter, `Up/Down Arrow` to navigate results +- The folder picker is a standard file dialog - navigate with `Arrow` keys, `Enter` to select + +### Method 2: Start Page Clone Button + +1. Open VS Code (no folder open) +2. The Start page appears +3. Navigate to "Clone Git Repository" button - press `Enter` +4. Paste repository URL → `Enter` +5. Choose destination folder +6. Open when prompted + +**Screen reader note:** The Start page is keyboard-accessible. `Tab` to navigate between "New File," "Open Folder," and "Clone Repository" buttons. + +### Method 3: From GitHub.com + +1. On any GitHub repository page, click the green "Code" button +2. Copy the HTTPS URL (recommended) or SSH URL +3. Open VS Code → `Ctrl+Shift+P` (Mac: `Cmd+Shift+P`) → "Git: Clone" +4. Paste URL → `Enter` +5. Choose destination → Open + +### Learning Cards: Cloning a Repository + +
    +Low vision users (zoom, high contrast) + +Cloning works the same as the Command Palette method above. A few tips for zoomed or magnified displays: + +1. The Command Palette (`Ctrl+Shift+P`) appears at the top-center of VS Code and scales with your zoom level - it remains visible even at 200%+ zoom. +2. When the folder picker dialog opens, it may extend beyond your visible area at high zoom. Use `Alt+Up Arrow` to navigate up in the folder tree and `Enter` to select. The dialog title bar shows your current location. +3. After cloning, the Explorer panel (`Ctrl+Shift+E`) shows the file tree. At high zoom, use `Ctrl+-` to temporarily reduce zoom if the tree is hard to scan, then `Ctrl+=` to restore. +4. If you use a high contrast theme (Settings: `Ctrl+,` then search "color theme"), file status colours in the Explorer (green for added, yellow for modified) may be subtle. Enable **Editor Decorator Colors** or rely on the Source Control panel (`Ctrl+Shift+G`) where status letters (M, A, D) are shown as text. + +
    + +
    +GitHub.com web interface (no local tools needed) + +If you cannot install Git or VS Code, you can work directly in the browser: + +1. Navigate to the repository on GitHub.com +2. Press `.` (period) to open **github.dev** - a browser-based VS Code editor +3. The full repository opens in an editor with file tree, search, and editing +4. Changes are committed directly to GitHub from the browser + +Alternatively, for quick edits: + +1. Navigate to any file on GitHub +2. Press `E` to open the file editor +3. Make changes and commit from the web editor + +**Note:** github.dev does not support terminal commands or local Git operations. For full Git workflows (branching, staging individual lines, stash), use desktop VS Code. + +
    + +
    +CLI (git / gh) + +Clone from your terminal using either standard Git or GitHub CLI: + +```bash +# Standard Git clone +git clone https://github.com/Community-Access/vscode-sci-fi-themes.git +cd vscode-sci-fi-themes + +# GitHub CLI clone (shorter syntax, handles auth automatically) +gh repo clone Community-Access/vscode-sci-fi-themes +cd vscode-sci-fi-themes + +# Clone into a specific folder +git clone https://github.com/Community-Access/vscode-sci-fi-themes.git ~/projects/themes + +# Clone only the default branch (faster for large repos) +gh repo clone Community-Access/vscode-sci-fi-themes -- --single-branch + +# Verify the clone +git status +git remote -v +``` + +**Screen reader advantage:** Terminal output is plain text. After cloning, `git status` confirms you are on the default branch with a clean working tree. + +
    + +**Why HTTPS over SSH for this workshop:** HTTPS works immediately with no setup. SSH requires key generation and configuration (see [Appendix D: Git Authentication](appendix-d-git-authentication.md) for SSH setup). + +### Try It Now: Clone the Sci-Fi Themes Repo + +To make your first clone meaningful and fun, try cloning the **VS Code Sci-Fi Thinking Phrases** repository: + +**Repository URL:** `https://github.com/community-access/vscode-sci-fi-themes.git` + +This repo contains custom loading phrases for GitHub Copilot Chat from three sci-fi universes: +- **Star Trek** — Engage warp drive and run diagnostics +- **The Hitchhiker's Guide** — Consult the Infinite Improbability Drive +- **Star Wars** — Read the ripples in the Force + +#### Why Clone This? + +- It's a real, working repository with multiple files to explore +- You'll see a practical use of cloning (customizing your personal VS Code setup) +- After cloning, you can pick a theme and apply it to your `settings.json` +- When you open Copilot Chat, you'll see your custom phrases appear! + +#### Quick Start + +1. Clone: `Ctrl+Shift+P` → "Git: Clone" → paste URL above → `Enter` +2. Choose a destination folder and open when prompted +3. Navigate to the `themes/` folder and pick a `.json` file (star-trek, hitchhikers, or star-wars) +4. Copy the `chat.agent.thinking.phrases` setting into your VS Code `settings.json` +5. Reload VS Code: `Ctrl+Shift+P` → "Developer: Reload Window" +6. Open Copilot Chat (`Ctrl+Shift+I`) and ask a question—watch your custom phrases appear! + +See `CLONE-THIS-REPO.md` in that repo for full instructions. + +
    +Web alternative (github.com) + +If you prefer not to clone locally, you can work entirely on GitHub.com: + +1. Navigate to the repository on GitHub +2. Click any file to view it, then click the **pencil icon** (Edit) to modify it directly in the browser +3. GitHub automatically creates a branch and commit for your edit +4. When you save, GitHub prompts you to open a pull request + +This approach requires no local tools - just a browser. It works well for documentation changes and small edits. For larger changes, cloning to VS Code gives you a full editor with multi-file editing, Git staging, and the Accessible Diff Viewer. + +
    + +
    +GitHub CLI (gh) alternative + +Clone a repository with one command: + +```bash +# Clone using owner/name (no URL needed) +gh repo clone community-access/vscode-sci-fi-themes + +# Clone and cd into the folder +gh repo clone community-access/vscode-sci-fi-themes && cd vscode-sci-fi-themes + +# Open the cloned repo in VS Code +gh repo clone community-access/vscode-sci-fi-themes && code vscode-sci-fi-themes +``` + +
    + + +## 2. The Source Control Panel - Complete Walkthrough + +The Source Control panel (`Ctrl+Shift+G` - Mac: `Cmd+Shift+G`) is where all Git operations happen in VS Code. This section provides a complete screen reader walkthrough of every interactive element. + +### Opening the Source Control Panel + +**Shortcut:** `Ctrl+Shift+G` (Mac: `Cmd+Shift+G`) + +#### What opens + +- A sidebar panel on the left side of VS Code +- Focus lands on the first interactive element (usually the commit message input or the first changed file) + +#### Panel structure from top to bottom + +1. **Source Control title bar** (heading level 2) + - Branch name displayed (example: "main" or "feature/add-documentation") + - View/More Actions button (three dots menu) + +2. **Commit message input** (multi-line text field) + - Type your commit message here + - Announced as "Source Control Input, edit, multi-line" + +3. **Commit button** (or "Publish Branch" if this is a new branch) + - Shortcut: `Ctrl+Enter` (Mac: `Cmd+Enter`) when focused in the message input + +4. **Changes section** (collapsible tree) + - Lists all modified files not yet staged + - Announced as "Changes, expanded" or "Changes, collapsed" + - Count shown (example: "Changes 3") + +5. **Staged Changes section** (collapsible tree) + - Lists files staged for commit + - Empty if nothing staged yet + - Announced as "Staged Changes, expanded" + +6. **Merge Changes section** (appears only during a merge) + - Lists files with conflicts + - See Section 9 for conflict resolution workflow + +### Screen Reader Navigation in the Source Control Panel + +#### NVDA/JAWS + +- The panel is a web-based tree view +- Use `Up/Down Arrow` to navigate between items +- Use `Right Arrow` to expand a section (Changes, Staged Changes) +- Use `Left Arrow` to collapse a section +- Use `Enter` to open a file diff +- Use `Space` to stage/unstage a file (when focused on a file item) + +#### VoiceOver + +- Navigate with `VO+Arrow` keys +- `VO+Space` to activate (open diff or stage/unstage) +- The panel is announced as a "group" containing lists + +**Key point:** The Source Control panel is **not** a standard file tree. It's a specialized Git status view. Each changed file is an interactive item with a context menu. + +### What Each File Shows + +When a file appears in the Changes or Staged Changes list, VS Code shows a status letter: + +| Letter | Meaning | +| -------- | --------- | +| M | Modified - file exists and was changed | +| A | Added - new file, not in Git yet | +| D | Deleted - file was removed | +| R | Renamed - file was moved or renamed | +| U | Untracked - file exists but Git is ignoring it | +| C | Conflict - file has merge conflicts (see Section 9) | + +**Screen reader announcement:** "docs/GUIDE.md, Modified" or "README.md, Added" + +### Context Menu Actions (Right-Click or Shift+F10) + +When focused on any file in the Source Control panel: + +| Action | What It Does | +| -------- | ------------- | +| Open File | Opens the file in the editor (same as `Enter`) | +| Open Changes | Opens side-by-side diff view (same as `Enter`) | +| Stage Changes | Moves file from Changes → Staged Changes | +| Unstage Changes | Moves file from Staged Changes → Changes | +| Discard Changes | **Dangerous** - deletes your local edits, restores file to last commit | +| Stage Selected Ranges | Stage only specific lines (see Section 4) | +| Revert Selected Ranges | Discard changes to specific lines only | + +**Screen reader tip:** Use `Shift+F10` to open the context menu. Navigate options with `Up/Down Arrow`. Press `Enter` to select. + +### Learning Cards: Source Control Panel + +
    +Low vision users (zoom, high contrast) + +The Source Control panel adapts well to zoom and high contrast settings: + +1. **At high zoom (200%+):** The panel may narrow. File names truncate but the status letter (M, A, D) remains visible at the end of each row. Hover over truncated names to see the full path in a tooltip. +2. **High contrast themes:** Status colours are reinforced by the status letter (M/A/D/R/U/C), so you do not rely on colour alone. To switch to a high contrast theme: `Ctrl+Shift+P` then type "Preferences: Color Theme" and select "High Contrast" or "High Contrast Light." +3. **The commit message input** is a multi-line text area. At high zoom it may appear narrow - it expands vertically as you type. Use `Ctrl+Enter` to commit from anywhere in the input (not `Enter`, which adds a new line). +4. **Diff views** opened from the panel use red/green highlighting. In high contrast themes these use distinct border patterns instead of subtle colour shading. Press `F7` to jump between change hunks rather than scrolling through large diffs visually. +5. **Minimap:** If the minimap (the narrow code preview strip on the right edge of the editor) is distracting at high zoom, disable it: Settings (`Ctrl+,`) then search "minimap enabled" and uncheck it. + +
    + +
    +CLI equivalent: viewing Git status + +The Source Control panel shows the same information as these terminal commands: + +```bash +# See all modified, staged, and untracked files +git status + +# Short format (one letter per file, compact) +git status -s + +# See what is staged (ready to commit) +git diff --cached --name-only + +# See what is modified but not staged +git diff --name-only + +# See both staged and unstaged differences with content +git diff # unstaged changes +git diff --cached # staged changes +``` + +**The letters match:** `M` = modified, `A` = added, `D` = deleted, `R` = renamed, `??` = untracked. + +
    + + +## 3. Branch Management + +Branches are how you organize work in Git. Every repository starts with a `main` or `master` branch. You create new branches for features, bug fixes, or experiments. + +### Viewing the Current Branch + +#### Where it's shown + +1. Bottom-left corner of VS Code (status bar) - visual users see it immediately +2. Source Control panel title bar +3. Command Palette: `Ctrl+Shift+P` (Mac: `Cmd+Shift+P`) → "Git: Show Git Output" + +#### Keyboard access to status bar + +- The status bar is not in the standard keyboard navigation flow +- Use the Command Palette for branch operations instead + +> **Visual users:** You can also click the branch name in the bottom-left status bar to open the branch picker directly. + +### Creating a New Branch + +#### Command Palette method (recommended) + +1. `Ctrl+Shift+P` (Mac: `Cmd+Shift+P`) +2. Type "git create branch" +3. Select "Git: Create Branch..." +4. Type the new branch name (example: `feature/improve-docs`) +5. Press `Enter` + +VS Code: + +- Creates the branch +- Switches to it automatically +- Your working files stay exactly as they were + +#### Naming conventions + +- Use lowercase with hyphens: `feature/add-timeline-guide` +- Avoid spaces and special characters +- Be descriptive: `fix/heading-hierarchy` not `fix1` + +
    +Web alternative (github.com) - branch management + +Create and switch branches without leaving your browser: + +1. On the repository page, click the **branch dropdown** (shows "main" by default) +2. Type a new branch name in the search field +3. Click **"Create branch: your-branch-name from main"** +4. GitHub switches to the new branch immediately +5. Any file edits you make in the browser will be on this branch + +To switch between branches, click the branch dropdown and select the branch you want. + +
    + +
    +Git CLI alternative - branch management + +Manage branches from your terminal: + +```bash +# Create and switch to a new branch +git checkout -b feature/improve-docs + +# List all branches +git branch -a + +# Switch to an existing branch +git checkout main + +# Delete a branch (after merging) +git branch -d feature/improve-docs +``` + +
    + +### Switching Between Branches + +#### Command Palette method + +1. `Ctrl+Shift+P` (Mac: `Cmd+Shift+P`) +2. Type "git checkout" +3. Select "Git: Checkout to..." +4. A list of all branches appears +5. `Up/Down Arrow` to navigate +6. `Enter` to switch + +**Screen reader announcement:** "Branch: main" or "Branch: feature/add-timeline-guide" + +#### What happens when you switch + +- VS Code saves your current files +- Loads the files from the other branch +- If you have uncommitted changes, Git may block the switch (see "Stashing" in Section 10) + +### Deleting a Branch + +#### After your PR is merged, you can delete the branch + +1. `Ctrl+Shift+P` (Mac: `Cmd+Shift+P`) +2. Type "git delete branch" +3. Select "Git: Delete Branch..." +4. Choose the branch to delete from the list +5. Confirm + +**Note:** You cannot delete the branch you're currently on. Switch to `main` first. + +### Viewing All Branches + +**Command:** `Ctrl+Shift+P` → "Git: Show Git Output" → Branch list appears + +**Alternative:** Use the integrated terminal: + +```bash +git branch # Local branches only +git branch -a # All branches (including remote) +``` + +### Learning Cards: Branch Management + +
    +Low vision users (zoom, high contrast) + +1. **Branch name in the status bar:** The current branch name appears in the bottom-left corner of VS Code. At high zoom, the status bar may be partially off-screen. Use `Ctrl+Shift+P` then type "Git: Checkout to..." to see and switch branches from the Command Palette instead. +2. **Branch picker list:** When you open the branch picker from the Command Palette, the list shows all available branches. At high zoom, long branch names may truncate. Type the first few characters to filter the list - the filter is instant. +3. **Visual branch indicators in the Explorer:** Modified files on a branch show a coloured dot in the Explorer panel. In high contrast themes, these dots use distinct shapes or borders. The Source Control panel (`Ctrl+Shift+G`) is more reliable for seeing which files changed on your branch. + +
    + +
    +Screen reader users (NVDA / JAWS on Windows) + +#### Creating a branch + +1. Press `Ctrl+Shift+P` to open the Command Palette +2. Type "git create branch" - NVDA/JAWS announces results as you type +3. Press `Enter` on "Git: Create Branch..." +4. The input focus moves to a text field - type your branch name (e.g., `feature/add-docs`) +5. Press `Enter` - VS Code creates and switches to the branch +6. NVDA/JAWS announces the new branch name in the status bar notification + +#### Switching branches + +1. Press `Ctrl+Shift+P`, type "git checkout" +2. Select "Git: Checkout to..." +3. A list of branches appears - navigate with `Up/Down Arrow` +4. Each item is announced as the branch name (e.g., "main", "feature/add-docs") +5. Press `Enter` to switch +6. VS Code reloads files for that branch - you hear a status bar update + +#### Deleting a branch + +1. Switch to a different branch first (you cannot delete the branch you are on) +2. Press `Ctrl+Shift+P`, type "git delete branch" +3. Select "Git: Delete Branch..." +4. Navigate the list to find the branch to delete, press `Enter` + +
    + +
    +Screen reader users (VoiceOver on macOS) + +#### Creating a branch + +1. Press `Cmd+Shift+P` to open the Command Palette +2. Type "git create branch" - VoiceOver announces filtered results +3. Press `Return` on "Git: Create Branch..." +4. Type the branch name in the input field +5. Press `Return` to create and switch + +#### Switching branches + +1. Press `Cmd+Shift+P`, type "git checkout" +2. Select "Git: Checkout to..." +3. Use `VO+Down Arrow` to navigate the branch list +4. Press `Return` to switch + +#### Getting the current branch name + +1. Press `VO+M` to move to the menu bar, then `VO+Right Arrow` to the status bar area +2. Or use the Command Palette: `Cmd+Shift+P` then type "Git: Show Git Output" - the output pane includes the current branch + +
    + +
    +GitHub.com web interface + +Create and switch branches without leaving your browser: + +1. On the repository page, find the **branch dropdown** button (shows "main" by default) - it is above the file table +2. Click or activate the dropdown +3. Type a new branch name in the search field +4. Click **"Create branch: your-branch-name from main"** when it appears +5. GitHub switches to the new branch immediately +6. Any file edits in the browser will be on this branch + +To switch between branches: + +1. Click the branch dropdown +2. Select the branch you want - the page reloads with that branch's files + +To delete a branch: + +1. Navigate to the repository's Branches page: click the branch count link (e.g., "3 branches") near the branch dropdown, or go to `github.com/owner/repo/branches` +2. Find the branch +3. Click the trash can icon next to it + +
    + +
    +CLI (git / gh) + +Manage branches from your terminal: + +```bash +# Create and switch to a new branch +git checkout -b feature/improve-docs + +# Or use the newer 'switch' command +git switch -c feature/improve-docs + +# List local branches (current branch marked with *) +git branch + +# List all branches including remote-tracking +git branch -a + +# Switch to an existing branch +git checkout main +# or +git switch main + +# Delete a branch (safe - only if merged) +git branch -d feature/improve-docs + +# Force delete a branch (even if not merged) +git branch -D feature/improve-docs + +# Rename the current branch +git branch -m new-name + +# Push a new branch to GitHub for the first time +git push -u origin feature/improve-docs + +# Delete a remote branch +git push origin --delete feature/improve-docs +``` + +Using GitHub CLI: + +```bash +# Create a branch linked to an issue (auto-names from issue title) +gh issue develop 42 --checkout + +# List remote branches +gh api repos/{owner}/{repo}/branches --jq '.[].name' +``` + +
    + + +## 4. Staging Changes - Files, Lines, and Chunks + +Git has a two-step commit process: + +1. **Stage** the changes you want to include +2. **Commit** those staged changes + +This lets you commit only part of your work, leaving the rest for a later commit. + +### Staging an Entire File + +
    +Visual / mouse users + +1. Open Source Control: `Ctrl+Shift+G` (Mac: `Cmd+Shift+G`) +2. Hover over a file in the "Changes" list - a **+** icon appears to its right +3. Click the **+** to stage that file +4. Or right-click a file → "Stage Changes" + +
    + +
    +Low vision users (zoom, high contrast) + +1. Open Source Control: `Ctrl+Shift+G` (Mac: `Cmd+Shift+G`) +2. At high zoom, the **+** (stage), **undo** (discard), and **open file** icons may be small. Instead of hovering: + - Right-click any file in the Changes list to get a full-size context menu with "Stage Changes", "Discard Changes", and other options + - Or use `Ctrl+Shift+P` then type "Git: Stage Changes" to stage the currently open file +3. The file moves from "Changes" to "Staged Changes" - both section headings include a count (e.g., "Changes 2", "Staged Changes 1") so you can confirm the move without relying on colour alone. +4. In high contrast themes, staged files show a distinct background or border in the Staged Changes section. + +
    + +
    +Screen reader users (NVDA / JAWS / VoiceOver) + +1. Open Source Control: `Ctrl+Shift+G` (Mac: `Cmd+Shift+G`) +2. Navigate to the file in the "Changes" list +3. Press `Ctrl+Enter` (Mac: `Cmd+Enter`) to stage immediately + +#### Alternative (keyboard shortcut) + +- Focus the file → press `Space` + +#### Alternative (context menu) + +- Focus the file → press `Shift+F10` (Mac: `Ctrl+Return`) → select "Stage Changes" + +
    + +#### What happens + +- The file moves from "Changes" → "Staged Changes" +- A green "A" or "M" indicator appears + +### Staging Multiple Files at Once + +1. `Ctrl+Shift+G` (Mac: `Cmd+Shift+G`) to open Source Control +2. Navigate to the "Changes" section heading +3. Press `Shift+F10` (Mac: `Ctrl+Return`) to open context menu on the section itself +4. Select "Stage All Changes" + +All modified files move to "Staged Changes." + +### Staging Individual Lines or Chunks + +**This is one of Git's most powerful features:** You can stage only specific lines of a file, leaving other changes unstaged. + +#### Workflow + +1. Open Source Control: `Ctrl+Shift+G` (Mac: `Cmd+Shift+G`) +2. Navigate to a file in "Changes" +3. Press `Enter` to open the diff view +4. The diff shows your changes side-by-side or inline +5. Navigate to a changed line (use `Arrow` keys or `F7` for next hunk) +6. Press `Shift+F10` (Mac: `Ctrl+Return`) to open context menu +7. Select "Stage Selected Lines" + +**Result:** Only those lines are staged. The rest of the file remains in "Changes." + +#### Use case for this workshop + +- You fixed a typo and added a new section in the same file +- You want to commit the typo fix separately from the new content +- Stage only the typo fix lines, commit them with message "fix: typo in heading" +- Then stage the new section, commit with message "docs: add Timeline View guide" + +**Screen reader tip:** In the diff view, press `Alt+H` to see Accessible Help for diff-specific keyboard shortcuts. + +
    +Web alternative (github.com) - editing files + +On GitHub.com, there is no staging step. When you edit a file in the browser: + +1. Click the **pencil icon** on any file to open the web editor +2. Make your changes +3. Click **"Commit changes"** - GitHub creates the commit directly +4. Choose to commit to the current branch or create a new branch and PR + +This is the simplest workflow if you are making a focused change to one file. For multi-file changes, VS Code's staging system gives you more control. + +
    + +
    +Git CLI alternative - staging + +Stage files from your terminal: + +```bash +# Stage a specific file +git add docs/GUIDE.md + +# Stage all changes +git add . + +# Stage specific lines interactively +git add -p docs/GUIDE.md +# Git shows each change hunk and asks: stage this? (y/n/s/e) + +# Unstage a file +git restore --staged docs/GUIDE.md + +# Check what is staged vs unstaged +git status +``` + +
    + +### Unstaging Files + +#### Reverse the process + +1. Focus the file in "Staged Changes" +2. Press `Ctrl+Enter` (Mac: `Cmd+Enter`) or `Space` +3. File moves back to "Changes" + +### Learning Cards: Staging Changes + +
    +Screen reader users + +- In Source Control (`Ctrl+Shift+G`), press `+` or `Space` on a file to stage it -- your screen reader announces the file moving from "Changes" to "Staged Changes" +- To stage individual lines, open the file diff (`Enter` on the file), select lines with `Shift+Up/Down`, then use Command Palette: "Git: Stage Selected Ranges" +- Press `Ctrl+Z` in the Source Control panel to unstage the last staged file if you staged the wrong one + +
    + +
    +Low vision users + +- Staged files appear under a separate "Staged Changes" heading with a green `+` icon -- look for the section break in the Source Control panel +- The inline diff view highlights added lines in green and removed lines in red; use `Ctrl+=` to zoom if the colors are hard to distinguish +- Right-click a file in the Source Control panel for a context menu with "Stage Changes", "Discard Changes", and "Open File" options + +
    + +
    +Sighted users + +- Hover over a file in the Changes list to see `+` (stage), curved arrow (discard), and file-open icons appear on the right +- Click the `+` icon next to "Changes" header to stage all files at once, or click `+` on individual files for selective staging +- The Source Control badge number on the Activity Bar decreases as you stage and commit changes + +
    + + +## 5. Committing with Screen Readers + +### The Commit Workflow + +#### Standard process + +1. Open Source Control: `Ctrl+Shift+G` (Mac: `Cmd+Shift+G`) +2. Stage changes (see Section 4) +3. Focus the commit message input (usually `Tab` or `Shift+Tab` to reach it) +4. Type your commit message +5. Press `Ctrl+Enter` (Mac: `Cmd+Enter`) to commit + +### Learning Cards: Committing + +
    +Visual / mouse users + +1. Open Source Control (`Ctrl+Shift+G`) +2. Stage your files (click the **+** icon next to each file, or click **Stage All Changes** above the Changes section header) +3. Click in the **"Message"** text area at the top of the Source Control panel +4. Type your commit message +5. Click the **Commit** button (checkmark icon) or press `Ctrl+Enter` +6. If nothing is staged, VS Code asks if you want to stage all changes and commit directly - click "Yes" if that is what you want + +
    + +
    +Low vision users (zoom, high contrast) + +1. The commit message input is at the top of the Source Control panel. At high zoom it may appear as a narrow rectangle - it expands vertically as you type. +2. The **Commit button** may show only as a small checkmark icon at high zoom. Use `Ctrl+Enter` from inside the message input instead - this is more reliable than finding the button visually. +3. After committing, the Staged Changes section clears. The count next to the section heading drops to 0, confirming the commit was recorded. +4. If you need to see your recent commits, use the Timeline view (`Ctrl+Shift+E`, navigate to the Timeline section at the bottom of Explorer) where each commit shows full message text at a readable size. + +
    + +#### Screen reader experience + +#### NVDA/JAWS + +- The commit input is announced as "Source Control Input, edit, multi-line" +- You're automatically in Forms Mode - just start typing +- The input expands as you type (supports multi-line messages) +- Press `Ctrl+Enter` (Mac: `Cmd+Enter`) to commit (not `Enter`, which adds a new line) + +#### VoiceOver + +- `VO+Tab` to navigate to the input +- `VO+Shift+Down` to interact +- Type your message +- `Ctrl+Enter` to commit +- `VO+Shift+Up` to stop interacting + +### Writing Good Commit Messages + +See [Culture & Etiquette: Writing Good Commit Messages](08-open-source-culture.md#writing-good-commit-messages) for format guidance. + +#### Quick reference + +```text +fix: correct heading hierarchy in GUIDE.md + +Fixes #42 +``` + +#### Format + +- First line: type + colon + short summary (50 characters max) +- Blank line +- Optional body: detailed explanation +- Optional footer: "Fixes #123" to link to issue + +**Common types:** `feat:`, `fix:`, `docs:`, `style:`, `refactor:`, `test:`, `chore:` + +
    +Git CLI alternative - committing + +Commit from your terminal: + +```bash +# Commit staged changes with a message +git commit -m "fix: correct heading hierarchy in GUIDE.md" + +# Commit with a multi-line message (opens your editor) +git commit + +# Stage all tracked files and commit in one step +git commit -am "docs: update screen reader instructions" +``` + +
    + +### What Happens After Commit + +- The "Staged Changes" section clears +- Your changes are now part of Git history +- The commit exists locally only - you must **push** to send it to GitHub (see Section 6) + + +## 6. Push and Pull Operations + +**Push** sends your local commits to GitHub. +**Pull** downloads new commits from GitHub to your local repository. + +### Pushing Your Commits to GitHub + +#### After committing locally + +1. Open Source Control: `Ctrl+Shift+G` (Mac: `Cmd+Shift+G`) +2. Look for the "Publish Branch" button (if this is a new branch) or "Sync Changes" button +3. Press `Enter` on that button + +#### Alternative: Command Palette + +1. `Ctrl+Shift+P` (Mac: `Cmd+Shift+P`) +2. Type "git push" +3. Select "Git: Push" +4. VS Code pushes your commits to GitHub + +### Learning Cards: Push and Pull + +
    +Low vision users (zoom, high contrast) + +1. **The Sync/Publish button** appears in the Source Control panel header area. At high zoom it may display as a small cloud icon with an arrow. If you cannot find it, use the Command Palette (`Ctrl+Shift+P` then type "Git: Push") - this is always reliable. +2. **Progress indication:** While pushing, VS Code shows a spinning icon in the status bar (bottom-left). At high zoom this may be off-screen. After pushing, run `Ctrl+Shift+P` then "Git: Show Git Output" to read the push log as scrollable text. +3. **Pull indicators:** When your branch is behind the remote, the status bar shows a down-arrow with a number (e.g., "↓2" means 2 commits to pull). At high zoom, the Command Palette approach (`Ctrl+Shift+P` then "Git: Pull") avoids needing to read the status bar. +4. **Auto-fetch:** Enable auto-fetch (Settings: search "git autofetch") so VS Code checks for remote changes every few minutes. This prevents surprise conflicts when you push. + +
    + +
    +Screen reader users (NVDA / JAWS on Windows) + +#### Pushing + +1. After committing, press `Ctrl+Shift+P`, type "git push", select "Git: Push" +2. NVDA/JAWS announces "Pushing..." in the status bar +3. On success, a notification appears: "Successfully pushed" - if using NVDA, check `NVDA+N` to read recent notifications +4. For a new branch (first push), use "Git: Publish Branch" instead - this sets up the upstream tracking + +#### Pulling + +1. Press `Ctrl+Shift+P`, type "git pull", select "Git: Pull" +2. NVDA/JAWS announces "Pulling..." then the status changes +3. If there are conflicts, the Source Control panel shows a "Merge Changes" section - navigate there with `Ctrl+Shift+G` then `Down Arrow` + +#### Checking sync status + +1. Press `Ctrl+Shift+P`, type "Git: Show Git Output" +2. The output pane opens with push/pull log messages in plain text +3. Use `Up/Down Arrow` to read line by line + +
    + +
    +Screen reader users (VoiceOver on macOS) + +#### Pushing + +1. Press `Cmd+Shift+P`, type "git push", select "Git: Push" +2. VoiceOver announces progress from the status bar +3. On success, a notification toast appears - press `VO+F3` to read the latest notification + +#### Pulling + +1. Press `Cmd+Shift+P`, type "git pull", select "Git: Pull" +2. VoiceOver announces when the pull completes +3. If conflicts exist, navigate to Source Control (`Cmd+Shift+G`) and review the Merge Changes section + +
    + +#### Screen reader feedback + +- NVDA/JAWS: Status bar announces "Pushing..." then "Pushed successfully" or an error message +- Check the Source Control panel for any error messages (they appear as banner notifications) + +
    +Git CLI alternative - push and pull + +Push and pull from your terminal: + +```bash +# Push commits to GitHub +git push + +# Push a new branch for the first time +git push -u origin feature/improve-docs + +# Pull changes from GitHub +git pull + +# Fetch without merging (see what changed first) +git fetch +git log HEAD..origin/main --oneline +``` + +
    + +
    +Web alternative (github.com) - push and pull + +On GitHub.com, there is no push/pull step - your commits are saved directly to GitHub when you use the web editor. If you edited on a branch, your changes are already on GitHub. Simply open a pull request from that branch. + +If your branch is behind `main`, look for the **"Update branch"** button on your PR page to pull in the latest changes. + +
    + +## What to do if push fails + +- **Error: "No upstream branch"** → You need to publish the branch first (Command Palette → "Git: Publish Branch") +- **Error: "Permission denied"** → Check your authentication (see [Appendix D: Git Authentication](appendix-d-git-authentication.md)) +- **Error: "Rejected - non-fast-forward"** → Someone else pushed changes; you need to pull first + +### Pulling Changes from GitHub + +#### When to pull + +- Before you start work each day +- When GitHub shows your branch is behind the remote +- When preparing to merge a PR + +#### How to pull + +1. `Ctrl+Shift+P` (Mac: `Cmd+Shift+P`) +2. Type "git pull" +3. Select "Git: Pull" +4. VS Code fetches and merges remote changes + +**If there are conflicts:** See Section 9. + +#### Auto-fetch setting + +- VS Code can check for remote changes automatically every few minutes +- Enable: Settings (`Ctrl+,` - Mac: `Cmd+,`) → search "git autofetch" → set to `true` + + +## Syncing Your Fork with the Upstream Repository + +When you fork a repository and the original (upstream) repository receives new commits, your fork gets out of date. Keeping your fork current prevents merge conflicts and ensures you're working with the latest code. + +### The GitHub "Sync fork" Button (Quickest Method) + +For straightforward updates, GitHub has a built-in sync button: + +1. Navigate to your fork on GitHub +2. On the repository page, look for the **"This branch is N commits behind owner/repo:main"** notice +3. Activate the **"Sync fork"** button next to it +4. GitHub automatically merges upstream changes into your fork's default branch +5. Then pull those changes to your local clone: `Git: Pull` from the Command Palette + +#### Screen reader path + +```text +On your fork's main page: +→ H or 3 to find the sync notice heading +→ Tab to "Sync fork" button → Enter +→ "Update branch" in the dialog → Enter +``` + +**Limitation:** The GitHub sync button only syncs the default branch. For other branches, use the git method below. + +### Adding the Upstream Remote (One-Time Setup) + +To sync locally using git, you first configure the upstream remote. This only needs to be done once per clone. + +```text +Step 1: Open the terminal in VS Code: Ctrl+` (backtick) +Step 2: Check your current remotes: + git remote -v + → You should see "origin" pointing to YOUR fork +Step 3: Add the upstream remote: + git remote add upstream https://github.com/ORIGINAL-OWNER/ORIGINAL-REPO.git +Step 4: Verify: + git remote -v + → You should now see both "origin" (your fork) and "upstream" (original) +``` + +#### Example for Accessibility Agents + +```bash +git remote add upstream https://github.com/community-access/accessibility-agents.git +``` + +### Fetching and Merging Upstream Changes + +Once your upstream remote is configured: + +```bash +# 1. Fetch all updates from upstream (does not change your files yet) +git fetch upstream + +# 2. Make sure you are on your default branch +git checkout main + +# 3. Merge upstream changes into your local branch +git merge upstream/main + +# 4. Push the updated branch to your fork on GitHub +git push origin main +``` + +## Via VS Code Command Palette + +```text +Ctrl+Shift+P → "Git: Fetch" → select "upstream" +Ctrl+Shift+P → "Git: Merge Branch" → select "upstream/main" +Ctrl+Shift+P → "Git: Push" +``` + +### When Conflicts Occur During Sync + +> **See also:** [Chapter 07: Merge Conflicts](07-merge-conflicts.md) for a dedicated walkthrough of conflict resolution. + +If you've made changes to the same files the upstream has changed, merge conflicts can occur during sync. The same conflict resolution flow applies - see Section 9 of this chapter. + +**Best practice:** Always sync before starting new work on a fork. A quick `git fetch upstream` at the start of each session prevents conflicts from accumulating. + + +## 7. Discarding Changes + +**Discarding = permanently deleting your local edits.** The file reverts to the state of the last commit. This is **irreversible.** + +### When to Discard + +- You made experimental changes and they didn't work +- You want to start over from the last commit +- You accidentally edited the wrong file + +### How to Discard Changes + +#### Single file + +1. Open Source Control: `Ctrl+Shift+G` +2. Navigate to the file in "Changes" +3. Press `Shift+F10` for context menu +4. Select "Discard Changes" +5. Confirm in the warning dialog (VS Code will ask "Are you sure?") + +#### All changes + +1. `Ctrl+Shift+G` +2. Navigate to the "Changes" section heading +3. `Shift+F10` for context menu +4. Select "Discard All Changes" +5. Confirm (this affects every modified file) + +**Screen reader warning:** VS Code shows a modal confirmation dialog. Navigate with `Tab`, select "Discard" or "Cancel" with `Enter`. + +### Learning Cards: Discarding Changes + +
    +Low vision users (zoom, high contrast) + +1. The **discard icon** (an undo arrow) appears when hovering over a file in the Changes list. At high zoom, right-click the file instead to get a full-size context menu with "Discard Changes." +2. The **confirmation dialog** that appears is a modal - it dims the background. In high contrast themes, the dialog has a clear border. The "Discard" button is typically the focused (primary) button. +3. For "Discard All Changes", right-click the "Changes" section heading to get the context menu. +4. After discarding, the file disappears from the Changes list. Check the file count in the section heading to confirm (e.g., "Changes 2" becomes "Changes 1"). + +
    + +
    +Screen reader users (NVDA / JAWS on Windows) + +#### Single file + +1. Press `Ctrl+Shift+G` to open Source Control +2. Navigate to the file in the Changes section with `Down Arrow` +3. Press `Shift+F10` to open the context menu +4. Navigate to "Discard Changes" with `Down Arrow`, press `Enter` +5. A confirmation dialog appears - NVDA announces "Are you sure you want to discard changes" or similar +6. Press `Tab` to navigate between "Discard" and "Cancel", press `Enter` on your choice + +#### All files + +1. Navigate to the "Changes" section heading (announced as "Changes, expanded, N items") +2. Press `Shift+F10`, select "Discard All Changes" +3. Confirm in the dialog + +
    + +
    +Screen reader users (VoiceOver on macOS) + +1. Press `Cmd+Shift+G` to open Source Control +2. Use `VO+Arrow` keys to navigate to the file +3. Press `VO+Shift+M` to open the context menu (or `Ctrl+Return`) +4. Navigate to "Discard Changes", press `VO+Space` +5. In the confirmation dialog, use `VO+Right Arrow` to reach the buttons, `VO+Space` to activate + +
    + +
    +CLI (git / gh) + +Discard changes from your terminal: + +```bash +# Discard changes to a specific file (restore to last commit) +git restore docs/GUIDE.md + +# Discard all unstaged changes +git restore . + +# Discard staged changes (unstage first, then restore) +git restore --staged docs/GUIDE.md +git restore docs/GUIDE.md + +# Nuclear option: discard ALL changes (staged and unstaged) +git checkout -- . + +# Preview what would be discarded before doing it +git diff # shows unstaged changes +git diff --cached # shows staged changes +``` + +> **Safety tip:** Run `git diff` before `git restore` to review what you are about to lose. Unlike VS Code's discard, there is no confirmation prompt in the terminal. + +
    + +### Safer Alternative: Stash Instead of Discard + +If you're not sure whether you'll need these changes later, use **stash** (Section 10) instead of discard. Stash saves your changes temporarily without committing them. + +### Deleting a File from the Repository (Git Delete / git rm) + +**Git Delete** removes a file from both your working directory AND Git's tracking. This is different from discarding changes - it permanently removes the file from the repository history going forward. + +#### How to use + +1. Open the file you want to remove in the editor +2. `Ctrl+Shift+P` (Mac: `Cmd+Shift+P`) +3. Type "Git: Delete" +4. Confirm the deletion + +The file is staged for deletion - you still need to commit to record the removal. + +#### When to use Git Delete vs. just deleting the file + +- Simply deleting a file from Explorer leaves it as an "untracked deletion" in Git +- Using `Git: Delete` (git rm) stages the deletion in one step +- Use `git rm` when you want to track the file removal as part of your next commit + +### Learning Cards: Deleting a File from the Repository + +
    +Visual / mouse users + +1. Right-click the file in the Explorer panel (`Ctrl+Shift+E`) +2. Select "Delete" to delete from your file system +3. The file appears in Source Control (`Ctrl+Shift+G`) under Changes with a "D" (deleted) status +4. Stage and commit the deletion to record it in Git + +Alternatively: `Ctrl+Shift+P` then "Git: Delete" removes the file and stages the deletion in one step. + +
    + +
    +Low vision users (zoom, high contrast) + +1. The easiest approach at high zoom is `Ctrl+Shift+P` then type "Git: Delete" - this works on the currently open file and avoids finding small context menu targets. +2. After deletion, confirm in Source Control (`Ctrl+Shift+G`) - the file appears with a "D" status letter. The "D" is text, not colour-only, so it works in all themes. +3. Stage and commit as normal. + +
    + +
    +Screen reader users (NVDA / JAWS / VoiceOver) + +1. Open the file you want to remove in the editor +2. Press `Ctrl+Shift+P` (Mac: `Cmd+Shift+P`), type "Git: Delete" +3. Select the command - the file is deleted and staged for removal +4. Navigate to Source Control (`Ctrl+Shift+G`) - the file is announced as "filename, Deleted" in the Staged Changes section +5. Write a commit message and press `Ctrl+Enter` to commit the removal + +**NVDA/JAWS note:** The file disappears from the Explorer tree. If you navigate there, you will no longer hear the filename. + +
    + +
    +GitHub.com web interface + +1. Navigate to the file on GitHub +2. Click the three-dot menu ("...") in the file header +3. Select "Delete file" +4. Write a commit message describing why the file was removed +5. Choose to commit directly or open a PR +6. Click "Commit changes" + +For screen reader users on GitHub: press `Tab` to navigate to the file actions menu, then `Enter` to open it. + +
    + +
    +CLI (git / gh) + +```bash +# Remove a file and stage the deletion in one step +git rm docs/old-file.md + +# Remove a file but keep it locally (stop tracking only) +git rm --cached docs/old-file.md + +# Remove an entire directory +git rm -r old-folder/ + +# Commit the deletion +git commit -m "chore: remove outdated documentation file" + +# Verify the file is no longer tracked +git status +``` + +
    + + +## 8. Timeline View - File History and Blame + +The **Timeline view** shows the Git history of the currently open file: every commit that touched this file, who made it, and when. + +### Opening Timeline View + +#### Method 1: Explorer Sidebar + +1. Open Explorer: `Ctrl+Shift+E` +2. At the bottom of the Explorer, there's a "Timeline" section +3. `Tab` or `Arrow` to navigate into Timeline +4. The list shows all commits affecting the currently open file + +#### Method 2: Command Palette + +1. Open a file in the editor +2. `Ctrl+Shift+P` +3. Type "timeline" +4. Select "View: Show Timeline" + +### What Timeline Shows + +For each commit entry: + +- **Commit message** (first line) +- **Author name** +- **Relative time** (example: "3 days ago" or "2 hours ago") +- **Commit hash** (short form, like `a3f2b9c`) + +**Screen reader announcement:** "docs: add Timeline Guide, Jeff, 2 days ago" + +### Viewing a Commit's Changes + +1. Navigate to a commit in the Timeline list +2. Press `Enter` +3. A diff view opens showing what changed in that specific commit + +This is incredibly useful for understanding: + +- When a particular line was added +- Why a section was removed +- What the file looked like at any point in history + +### Git Blame - Line-by-Line History + +**Git Blame** shows who last modified each line of the file. + +#### How to access + +1. Open a file in the editor +2. `Ctrl+Shift+P` +3. Type "git blame" +4. Select "Git: Toggle Blame" + +#### What appears + +- Inline annotations next to every line (visually) +- Hover over a line to see commit details + +#### For screen reader users + +- The inline blame annotations can add noise +- Use **Timeline view instead** to see recent changes to the whole file +- Use `Ctrl+F` to search the Timeline list for a specific author or date + +**Useful blame settings** (add to `.vscode/settings.json` or user Settings): + +| Setting | Default | What It Does | +| --------- | --------- | ------------- | +| `git.blame.ignoreWhitespace` | `false` | When `true`, whitespace-only changes (reformatting) are excluded from blame - useful when code was reformatted without logic changes | +| `git.blame.editorDecoration.disableHover` | `false` | When `true`, disables the hover tooltip on blame annotations - reduces screen reader noise if you find the blame decorations intrusive | + +### Learning Cards: Timeline and History + +
    +Low vision users (zoom, high contrast) + +1. **Timeline panel location:** It is at the bottom of the Explorer sidebar (`Ctrl+Shift+E`). At high zoom you may need to scroll down in the Explorer to find it. If the Timeline section is collapsed, click the **Timeline** heading to expand it. +2. **Reading commit entries:** Each entry shows the commit message, author, and time. At high zoom, long commit messages may truncate. Click any entry to open the diff view, which shows the full message in the editor tab title. +3. **Diff view at high zoom:** Red/green highlighting shows removed/added lines. In high contrast themes, changes use distinct borders or backgrounds. Press `F7` to jump through changes with a visible highlight that is easier to track than scrolling. +4. **Git Blame at high zoom:** The inline blame annotations are small grey text at the end of each line. At high zoom they may overlap with code. Use Timeline view instead for a more readable list of who changed what. + +
    + +
    +Screen reader users (NVDA / JAWS on Windows) + +#### Opening Timeline + +1. Press `Ctrl+Shift+E` to open Explorer +2. Press `Tab` repeatedly or `Down Arrow` to navigate past the file tree to the "Timeline" section +3. Press `Right Arrow` to expand it if collapsed +4. Navigate commit entries with `Up/Down Arrow` +5. Each entry is announced as: "commit message, author, time" (e.g., "docs: add Timeline Guide, Jeff, 2 days ago") +6. Press `Enter` on any entry to open its diff view + +#### Reading a diff with screen reader + +1. In the diff view, press `Alt+F2` to open the Accessible Diff Viewer +2. The Accessible Diff Viewer presents changes as a text list: each line shows `+` (added), `-` (removed), or unchanged +3. Navigate with `Up/Down Arrow` to read each line +4. Press `Escape` to close the Accessible Diff Viewer + +#### Git Blame + +1. Open a file, press `Ctrl+Shift+P`, type "Git: Toggle Blame" +2. Blame annotations appear inline - NVDA reads them when navigating lines +3. To reduce noise, disable blame (repeat the toggle command) and use Timeline instead + +
    + +
    +Screen reader users (VoiceOver on macOS) + +#### Opening Timeline + +1. Press `Cmd+Shift+E` to open Explorer +2. Use `VO+Down Arrow` to navigate below the file tree to the Timeline section +3. Press `VO+Space` to expand if collapsed +4. Navigate entries with `VO+Down Arrow` +5. Press `VO+Space` on a commit to open its diff + +#### Accessible Diff Viewer + +1. In any diff view, press `Option+F2` to open the Accessible Diff Viewer +2. Read changes line by line with `VO+Down Arrow` +3. Press `Escape` to close + +
    + +
    +CLI (git / gh) - history and blame + +```bash +# View commit history for the entire repo +git log --oneline + +# View history for a specific file +git log --oneline docs/GUIDE.md + +# View history with what changed in each commit +git log -p docs/GUIDE.md + +# View who last changed each line (blame) +git blame docs/GUIDE.md + +# Blame with short commit hashes and author +git blame --date=short docs/GUIDE.md + +# Show a specific commit's changes +git show abc1234 + +# Show what changed between two commits +git diff abc1234..def5678 + +# Show commits by a specific author +git log --author="Jeff" --oneline + +# Show commits in the last 7 days +git log --since="7 days ago" --oneline +``` + +Using GitHub CLI: + +```bash +# View recent commits from the web +gh api repos/{owner}/{repo}/commits --jq '.[0:5] | .[] | .commit.message' + +# View PR history +gh pr list --state all --limit 10 +``` + +**Screen reader advantage:** `git log --oneline` and `git blame` produce clean, columnar text output. Read line by line with arrow keys in the terminal. + +
    + + +## 9. Resolving Merge Conflicts in VS Code + +Merge conflicts happen when two people edit the same lines of a file. Git can't decide which version to keep, so it asks you to choose. + +**Prerequisite:** Read [Merge Conflicts](07-merge-conflicts.md) for the underlying concepts. This section covers the VS Code-specific workflow. + +### How VS Code Displays Conflicts + +When you open a file with conflicts, you see something like: + +```markdown +<<<<<<< HEAD +## Timeline View - File History +======= +## Timeline View - Git History and Blame +>>>>>>> feature/improve-timeline-guide +``` + +**VS Code adds buttons above each conflict** (visually): + +- "Accept Current Change" (keeps HEAD version) +- "Accept Incoming Change" (keeps the other branch's version) +- "Accept Both Changes" (keeps both, one after the other) +- "Compare Changes" (opens side-by-side diff) + +### Screen Reader Workflow for Resolving Conflicts + +**The buttons are NOT accessible via keyboard.** Use this method instead: + +1. **Identify the conflict markers:** + - `<<<<<<<` marks the start + - `=======` separates the two versions + - `>>>>>>>` marks the end + +2. **Read both versions:** + - The section between `<<<<<<<` and `=======` is **your current branch** (HEAD) + - The section between `=======` and `>>>>>>>` is **the incoming branch** (the branch you're merging) + +3. **Decide what to keep:** + - Delete the conflict markers (`<<<<<<<`, `=======`, `>>>>>>>`) + - Delete the version you don't want + - Or rewrite the section combining both versions + - Save the file + +4. **Stage the resolved file:** + - `Ctrl+Shift+G` to open Source Control + - The file appears in "Merge Changes" section + - Stage it (presses `Ctrl+Enter` or `Space`) + +5. **Commit the merge:** + - Type commit message (or keep the auto-generated one: "Merge branch 'feature/...' into main") + - `Ctrl+Enter` (Mac: `Cmd+Enter`) to commit + +### Using Accessible Diff for Conflict Review + +**Better approach:** Use the Accessible Diff Viewer (`F7`) to navigate conflict hunks systematically. + +1. Open the conflicted file +2. Press `F7` to jump to the first conflict hunk +3. Press `Alt+F2` to open Accessible View +4. Read both versions clearly +5. Press `Escape` to return to editor +6. Manually edit to resolve +7. Press `F7` to jump to the next conflict +8. Repeat until all conflicts resolved + +#### This gives you structured, hunk-by-hunk navigation instead of searching for markers manually + +### Aborting a Merge + +If you want to cancel the merge and go back to before you started: + +1. `Ctrl+Shift+P` +2. Type "git abort" +3. Select "Git: Abort Merge" + +Everything returns to the pre-merge state. + +### Learning Cards: Resolving Merge Conflicts + +
    +Screen reader users + +- Press `F7` in a conflict file to enter the Accessible Diff Viewer and step through conflicts hunk by hunk with announced change types +- Conflict markers (`<<<<<<<`, `=======`, `>>>>>>>`) are read aloud as you arrow through lines -- listen for these to identify conflict boundaries +- After resolving all markers, stage the file with `Ctrl+Shift+G` then navigate to it and press `+`, then commit to complete the merge + +
    + +
    +Low vision users + +- VS Code highlights conflict regions with colored backgrounds: green for "Current Change" (yours) and blue for "Incoming Change" (theirs) +- The inline action buttons ("Accept Current", "Accept Incoming", "Accept Both") appear above each conflict -- they are visible at high zoom levels +- Use `Ctrl+Shift+M` to check the Problems panel for any remaining conflict markers you may have missed + +
    + +
    +Sighted users + +- Look for the colored conflict blocks in the editor: green background = your version, blue background = incoming version +- Click "Accept Current Change", "Accept Incoming Change", or "Accept Both Changes" above each conflict for one-click resolution +- The Source Control panel shows a merge badge when conflicts exist -- it clears after you commit the resolution + +
    + + +## 10. Stash Management + +**Stash** temporarily saves your uncommitted changes so you can switch branches or pull updates without committing half-finished work. + +### When to Use Stash + +- You need to switch branches but have uncommitted changes +- You want to pull updates from GitHub but have local edits +- You want to save experimental work without committing it + +### Creating a Stash + +#### Method 1: Command Palette + +1. `Ctrl+Shift+P` +2. Type "git stash" +3. Select "Git: Stash" +4. Optionally type a stash message (helps you remember what's in it) + +#### What happens + +- Your uncommitted changes disappear from the editor +- The files revert to the last commit +- Your changes are saved in a hidden Git stash +- You can now switch branches or pull safely + +### Viewing Stashes + +#### Command Palette + +1. `Ctrl+Shift+P` +2. Type "git stash list" +3. Select "Git: Show Stash" + +#### Alternative: Integrated Terminal + +```bash +git stash list +``` + +Output looks like: + +```text +stash@{0}: WIP on feature/docs: add Timeline guide +stash@{1}: WIP on main: fix typo +``` + +### Applying a Stash + +#### To restore your stashed changes + +1. `Ctrl+Shift+P` +2. Type "git stash apply" +3. Select "Git: Apply Latest Stash" + +#### Or to apply a specific stash + +1. `Ctrl+Shift+P` +2. Type "git stash pop" +3. Select "Git: Pop Stash..." +4. Choose which stash from the list + +#### Difference between Apply and Pop + +- **Apply**: restores changes and keeps the stash (you can apply it again later) +- **Pop**: restores changes and deletes the stash + +### Dropping a Stash + +If you no longer need what's in a stash: + +1. `Ctrl+Shift+P` +2. Type "git stash drop" +3. Select "Git: Drop Stash..." +4. Choose which stash to delete + +### Learning Cards: Stash Management + +
    +Visual / mouse users + +1. Open Source Control: `Ctrl+Shift+G` +2. In the Source Control panel, there may be a **"Stashes"** section below Staged Changes (visible when stashes exist) +3. Click a stash to see what it contains +4. Right-click a stash to Apply, Pop, or Drop it + +If the Stashes section is not visible, use the Command Palette: `Ctrl+Shift+P` then type "git stash" to access all stash commands. + +
    + +
    +Low vision users (zoom, high contrast) + +1. The Stashes section in the Source Control panel may be below the fold at high zoom. Scroll down in the panel, or use the Command Palette (`Ctrl+Shift+P` then "git stash") which is always accessible regardless of zoom level. +2. Stash names in the Command Palette list are full text (e.g., "stash@{0}: WIP on feature/docs: add Timeline guide") and respect your font size settings. +3. After applying a stash, your files reappear in the Changes section of Source Control. Check the file count to confirm. + +
    + +
    +Screen reader users (NVDA / JAWS on Windows) + +#### Creating a stash + +1. Press `Ctrl+Shift+P`, type "git stash" +2. Select "Git: Stash" - NVDA announces the result +3. An input appears asking for a stash message - type something descriptive (e.g., "WIP: documentation changes for Timeline section") +4. Press `Enter` - your changes disappear from Source Control and are saved in the stash +5. NVDA announces the Source Control panel update (file counts drop to 0) + +#### Applying a stash + +1. Press `Ctrl+Shift+P`, type "git stash pop" +2. Select "Git: Pop Stash..." +3. A list of stashes appears - navigate with `Up/Down Arrow` +4. Each item is announced with the stash message you wrote +5. Press `Enter` to apply and delete the stash +6. Your changes reappear in the Changes section + +#### Viewing stashes + +1. Press `Ctrl+Shift+P`, type "git stash list" +2. Or in the terminal: type `git stash list` and read the output line by line + +
    + +
    +Screen reader users (VoiceOver on macOS) + +1. Press `Cmd+Shift+P`, type "git stash" +2. Select "Git: Stash" and provide a message +3. Press `Return` +4. To apply: `Cmd+Shift+P`, type "git stash pop", select from the list with `VO+Down Arrow`, press `Return` + +
    + +
    +GitHub.com web interface + +GitHub.com does not have a stash feature. Stash is a local Git operation only. If you need to save work-in-progress without committing on GitHub.com: + +1. Create a draft commit on a temporary branch +2. Or use GitHub Codespaces (which runs a full VS Code environment in the browser and supports `git stash` in the terminal) + +
    + +
    +CLI (git / gh) - stash commands + +```bash +# Stash all uncommitted changes with a message +git stash push -m "WIP: documentation changes" + +# Stash including untracked (new) files +git stash push -u -m "WIP: including new files" + +# List all stashes +git stash list + +# Show what a specific stash contains +git stash show stash@{0} +git stash show -p stash@{0} # with full diff + +# Apply the most recent stash (keep stash) +git stash apply + +# Apply and delete the most recent stash +git stash pop + +# Apply a specific stash +git stash apply stash@{1} + +# Delete a specific stash +git stash drop stash@{0} + +# Delete ALL stashes (careful) +git stash clear +``` + +
    + + +## 10b. Emergency Recovery - git reflog + +`git reflog` is the safety net you reach for when something goes seriously wrong: an accidental hard reset, a lost branch, a rebase that destroyed commits you needed. It is the most underused recovery tool in Git. + +**What reflog records:** Every time the `HEAD` pointer moves - from commits, resets, rebases, checkouts, merges - Git quietly records it in the reflog. These entries are kept for 90 days by default. + +### When to Use Reflog + +| Scenario | What happened | Reflog solution | +| ---------- | -------------- | ------------------ | +| Deleted a branch by mistake | `git branch -D feature/x` | Find the last commit SHA from reflog → recreate branch | +| `git reset --hard` lost commits | Moved HEAD to older commit | Find the SHA before the reset → reset back to it | +| Rebase went wrong | Commits appear lost | Find pre-rebase HEAD → reset to it | +| Accidentally force-pushed | Local history destroyed | Find the SHA from reflog → restore | + +### Reading the Reflog in VS Code Terminal + +```bash +git reflog +``` + +Output looks like: + +```text +abc1234 HEAD@{0}: commit: Fix typo in README +bcd2345 HEAD@{1}: reset: moving to HEAD~1 +cde3456 HEAD@{2}: commit: Add accessibility section +def4567 HEAD@{3}: checkout: moving from main to feature/docs +``` + +Each line: ` HEAD@{N}: ` + +**Screen reader tip:** Run this in the integrated terminal (`Ctrl+Backtick`). The output is plain text - read line by line with ↓. You are looking for the SHA just before the action that caused the problem. + +### Recovering Lost Commits + +#### If you need to restore a commit that has been lost + +```bash +# Step 1 - Find the last good commit SHA in reflog +git reflog + +# Step 2 - Preview what that commit looked like +git show abc1234 + +# Step 3a - Create a new branch at that point (safest) +git branch recovery/my-lost-work abc1234 + +# Step 3b - OR reset the current branch to that point +git reset --hard abc1234 +``` + +> **Use `git branch` over `git reset --hard` when recovering** - creating a branch is non-destructive; you keep both the current state and the recovered state, then decide which to keep. + +### Recovering a Deleted Branch + +```bash +# Find the last commit on the deleted branch +git reflog | grep 'feature/deleted-branch-name' + +# Recreate the branch at that SHA +git checkout -b feature/deleted-branch-name abc1234 +``` + +### Why Reflog Is Local-Only + +Reflog records are stored in your local `.git/` directory and are **not pushed to GitHub**. If your entire local clone is destroyed (hard drive failure, `rm -rf`), reflog cannot help - but GitHub retains the pushed commits in the remote history. + +**Workshop tip:** If you run a reset or rebase during the workshop and lose something, immediately run `git reflog` before doing anything else. The recovery window is open as long as you haven't run `git gc`. + +### Learning Cards: Emergency Recovery + +
    +Screen reader users + +- Run `git reflog --oneline` in the terminal and arrow through the output -- each line announces a HEAD movement with its SHA and action description +- Copy the SHA you want to recover to by selecting it in the terminal (`Shift+Arrow`) then pressing `Ctrl+C`, then run `git checkout -b recovery ` +- Reflog entries are kept for 90 days -- you have time to recover, so do not panic + +
    + +
    +Low vision users + +- `git reflog` output is columnar text: SHA on the left, action description on the right -- increase terminal font size with `Ctrl+=` for readability +- Each reflog entry starts with `HEAD@{N}` where N is the number of steps back -- lower numbers are more recent +- Use `git log --oneline --graph` after recovery to visually confirm the branch history looks correct + +
    + +
    +Sighted users + +- Look for the SHA hash in the leftmost column of `git reflog` output -- these are the restore points you can checkout or reset to +- The action column (e.g., "commit:", "reset:", "checkout:") tells you what caused each HEAD movement +- After recovering with `git checkout -b`, verify in the Source Control panel that the branch appears with the expected files + +
    + + +## 11. Alternative Git Interfaces + +VS Code's Source Control panel is one way to use Git. These alternatives exist for different workflows. + +### GitHub Desktop + +- **Graphical Git client** +- Download: [desktop.github.com](https://desktop.github.com) +- Strengths: Visual diff review, simpler branch management for beginners +- Screen reader support: Partial - keyboard navigation works for core flows but some visual-only elements exist + +### GitHub CLI (`gh`) + +- **Command-line interface for GitHub operations** +- Install: `winget install GitHub.cli` (Windows) or `brew install gh` (macOS) +- Strengths: Fast, scriptable, plain-text output (predictable for screen readers) + +#### Common commands + +```bash +gh repo clone owner/repo # Clone a repository +gh issue list # List issues +gh pr create # Create a PR interactively +gh pr list # List your PRs +gh pr view 14 # Read PR #14 +``` + +See [Culture & Etiquette](08-open-source-culture.md) for more `gh` examples. + +### Git CLI (Terminal) + +- **The standard Git command-line interface** +- Included with VS Code (integrated terminal: `Ctrl+Backtick`) + +#### Common commands + +```bash +git status # Show modified files +git add . # Stage all changes +git commit -m "message" # Commit with message +git push # Push to GitHub +git pull # Pull from GitHub +git log # View commit history +``` + +**Screen reader tip:** Terminal output is plain text - more predictable than GUI elements for some operations. + + +## VS Code Keyboard Shortcuts - Git Operations Quick Reference + +| Action | Shortcut | +| -------- | ---------- | +| Open Source Control | `Ctrl+Shift+G` | +| Stage file | `Ctrl+Enter` (on file in Changes) | +| Unstage file | `Ctrl+Enter` (on file in Staged Changes) | +| Commit | `Ctrl+Enter` (in message input) | +| View file diff | `Enter` (on file in Source Control) | +| Next diff hunk | `F7` | +| Previous diff hunk | `Shift+F7` | +| Open Accessible Diff Viewer | `Alt+F2` (in diff view) | +| Accessible Help | `Alt+H` (in any panel) | +| Open Timeline view | `Ctrl+Shift+E` → navigate to Timeline section | +| Integrated terminal | `Ctrl+Backtick` | +| Delete file from repo (git rm) | `Ctrl+Shift+P` → "Git: Delete" | + + +## Try It: Clone, Branch, Commit + +**Time:** 5 minutes | **What you need:** VS Code with Git configured + +Do the complete Git workflow once, start to finish: + +1. **Clone** - Press `Ctrl+Shift+P`, type `Git: Clone`, press `Enter`. Paste `https://github.com/Community-Access/vscode-sci-fi-themes.git` and choose a folder. VS Code opens the repo. +2. **Create a branch** - Click the branch name in the status bar (bottom left) or press `Ctrl+Shift+P` → `Git: Create Branch`. Name it `chapter11/your-name`. +3. **Make a change** - Open a theme file in the `themes/` folder (for example, `star-trek-settings.json`). Add a new thinking phrase to the array. +4. **Stage** - Press `Ctrl+Shift+G` to open Source Control. Navigate to your changed file and press `Enter` to stage it (or use the `+` button). +5. **Commit** - Tab to the message input, type `feat: add new thinking phrase`, press `Ctrl+Enter`. +6. **Push** - Press `Ctrl+Shift+P` → `Git: Push`. + +**You're done.** You just completed the full Git cycle: clone → branch → edit → stage → commit → push. + +> **What success feels like:** Your change is on GitHub. You can verify by visiting the repository and switching to your branch. Every future contribution follows this same six-step pattern. And your Copilot Chat now has a custom sci-fi loading phrase you wrote. + +--- + +*Next: [Chapter 15: Code Review](15-code-review.md)* +*Back: [Chapter 13: How Git Works](13-how-git-works.md)* +*Related appendices: [Appendix E: Advanced Git](appendix-e-advanced-git.md) | [Appendix D: Git Authentication](appendix-d-git-authentication.md)* + diff --git a/admin/qa-bundle/docs/15-code-review.md b/admin/qa-bundle/docs/15-code-review.md new file mode 100644 index 0000000..037bb7f --- /dev/null +++ b/admin/qa-bundle/docs/15-code-review.md @@ -0,0 +1,2902 @@ +# Code Review: PRs, Diffs, and Constructive Feedback + +> **Related appendices:** [Appendix G: VS Code Reference](appendix-g-vscode-reference.md) | [Appendix C: Markdown Reference](appendix-c-markdown-reference.md) +> **Authoritative sources:** [GitHub Docs: Reviewing changes in pull requests](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests) | [GitHub Accessibility Guide: Pull Request Reviews](https://accessibility.github.com/documentation/guide/pull-requests/) + + +> **Day 2, Block 2 Material** +> +> This chapter unifies PR management, accessible code review, and the reviewer's craft into one chapter. Part 1 covers the GitHub Pull Requests extension in VS Code. Part 2 covers accessible code review with diffs and inline comments. Part 3 adds the reviewer's judgment framework. + +--- + +## Part 1: The GitHub Pull Requests Extension + +> **See also:** [Appendix G: VS Code Reference](appendix-g-vscode-reference.md) for the complete list of GitHub Pull Requests extension keyboard shortcuts. + +> +> **Listen to Episode 13:** [The GitHub Pull Requests Extension](../admin/PODCASTS.md) - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. + +## Managing Pull Requests from VS Code + +> **Day 2, Block 2 Material** +> +> This guide covers the GitHub Pull Requests and Issues extension: viewing open PRs, checking out PR branches for local testing, reviewing PRs with screen reader-accessible tools, creating PRs directly from VS Code, using PR templates, and syncing PR status with GitHub. +> +> **Prerequisites:** [Working with Pull Requests](06-working-with-pull-requests.md), [Git & Source Control in VS Code](14-git-in-practice.md) +> +> **Mac keyboard shortcuts:** Throughout this chapter, all `Ctrl+` shortcuts use `Cmd+` on Mac, and `Alt+` shortcuts use `Option+` on Mac. For example: `Ctrl+Shift+P` → `Cmd+Shift+P`, `Ctrl+Shift+G` → `Cmd+Shift+G`, `Alt+F2` → `Option+F2`. Context menus (`Shift+F10` on Windows) use `Ctrl+Return` on Mac. + + +## Workshop Recommendation (Chapter 15, Part 1) + +Chapter 15, Part 1 introduces the **GitHub Pull Requests extension** for managing PRs directly from VS Code. + +- **Challenge count:** 2 guided challenges +- **Automation check:** none (extension installation and review state are account-local) +- **Evidence:** issue comment with confirmation of actions completed +- **Pattern:** install, check out, review, comment + +### Chapter 15, Part 1 Practice Set + +1. **Install the GitHub Pull Requests extension** - add the extension to VS Code and sign in with your GitHub account. +2. **Check out a PR and post a review comment** - download a PR branch locally, read the diff, and post one constructive review comment. + +### Practice 15.1 Step-by-Step: Install the Extension + +**Goal:** Install the GitHub Pull Requests and Issues extension and authenticate with your GitHub account. + +**Where you are working:** VS Code desktop with your Learning Room repository open. + +**Estimated time:** 3-5 minutes. + +1. Open the Extensions sidebar: `Ctrl+Shift+X` (Mac: `Cmd+Shift+X`). +2. Your screen reader announces "Extensions: Marketplace." The search box has focus. +3. Type `GitHub Pull Requests` in the search box and press `Enter`. +4. Navigate down the results list. Select **GitHub Pull Requests** (publisher: GitHub). +5. Activate the **Install** button. VS Code installs the extension and may show a notification. +6. After installation, VS Code prompts you to sign in. Activate **Sign in to GitHub**. +7. A browser window opens for GitHub OAuth. Approve the authorization and return to VS Code. +8. Verify: open the Explorer sidebar (`Ctrl+Shift+E`). You should now see a **GitHub** section in the sidebar showing Pull Requests and Issues. + +**Screen reader tip:** After step 5, if the install notification disappears before you can read it, open Command Palette (`Ctrl+Shift+P`) and run `Notifications: Focus Notification Toast`. + +**You are done when:** The GitHub section appears in your Explorer sidebar and shows pull requests from your Learning Room repository. + +### Practice 15.2 Step-by-Step: Check Out a PR and Post a Comment + +**Goal:** Check out someone else's PR branch locally, read the diff in VS Code, and post one constructive review comment. + +**Where you are working:** VS Code with the GitHub Pull Requests extension installed. + +**Estimated time:** 10-15 minutes. + +1. Open the Command Palette: `Ctrl+Shift+P` (Mac: `Cmd+Shift+P`). +2. Type `GitHub Pull Requests: Focus on Pull Requests View` and select it. The Pull Requests panel opens. +3. Navigate the list of open PRs. Find one that is **not yours** (a classmate's PR from Chapter 6, 7, or 14). +4. With the PR focused, press `Enter` or activate **Checkout** from the context menu (`Shift+F10` on Windows). VS Code switches to that PR's branch. +5. Open the Command Palette again and run `GitHub Pull Requests: Open Changed Files`. This shows the list of files the PR changed. +6. Open one changed file. VS Code opens the **Diff Editor** showing old content on the left and new content on the right. +7. Navigate the diff with the **Accessible Diff Viewer**: press `F7` to move to the next change, `Shift+F7` for the previous change. Your screen reader announces each change (added lines, removed lines). +8. Find one specific thing to comment on: a typo, an unclear sentence, a missing step, or something the author did well. +9. To add an inline comment: position your cursor on the line you want to comment on, then open Command Palette and run `GitHub Pull Requests: Add Comment`. Type your constructive comment and activate **Add Comment**. +10. If the inline comment method is difficult, navigate to the PR on GitHub.com instead and add your comment in the **Files changed** tab. + +**If checkout is blocked by permissions:** You can still complete this challenge in read-only mode. Skip step 4 and instead open the PR on GitHub.com. Use the **Files changed** tab to read the diff and post your comment there. + +**Screen reader tip:** In the Diff Editor, `F7` (Accessible Diff Viewer) is the most reliable way to navigate changes. It reads each hunk as a single block, which is much easier than navigating line by line. + +**You are done when:** You have posted at least one constructive review comment on someone else's PR. + +### Completing Chapter 15, Part 1: Submit Your Evidence + +Open your assigned setup or review practice issue and post a completion comment: + +```text +Chapter 15 Part 1 completed: +- Extension installed: yes / no +- Signed in to GitHub: yes / no +- PR reviewed: #[PR number by classmate] +- Comment posted: yes (inline / on GitHub.com) +- My comment was about: [one-sentence summary] +``` + +Close your Chapter 12 challenge issues when done. + +### Expected Outcomes + +- Student can install and authenticate the GitHub PR extension. +- Student can check out a PR branch in VS Code (or view it on GitHub.com). +- Student can navigate diffs using the Accessible Diff Viewer (`F7`). +- Student can post constructive, specific feedback on a classmate's work. + +### If You Get Stuck + +1. Extension does not install? Reload VS Code: `Ctrl+Shift+P`, then run `Developer: Reload Window`. +2. OAuth sign-in fails? Verify your GitHub account is active in the browser first, close VS Code, reopen, and retry. +3. PR list is empty? Switch to "All Open" view in the GitHub Pull Requests panel. +4. Checkout fails? Confirm you have write access to the repository. If not, use the read-only GitHub.com fallback. +5. Diff Editor is hard to navigate? Press `F7` for the Accessible Diff Viewer mode, which is purpose-built for screen readers. +6. Cannot find the Add Comment command? Use Command Palette and search for `GitHub Pull Requests: Add Comment`. +7. Ask facilitator to help verify the GitHub PR panel and model one review comment. +8. Finished but not sure you did it right? Compare your work against the [Challenge 11 reference solution](solutions/solution-11-day2-pr.md). + +> **Continue learning:** The GitHub Skills course [Review Pull Requests](https://github.com/skills/review-pull-requests) practices approving, requesting changes, and using suggestions in an interactive format. See [Appendix Z](appendix-z-github-skills.md) for the full catalog. + +### Learning Moment + +PR tooling multiplies your impact. Reviewing others' work refines your own standards and builds community trust. The comment you just wrote helps another student learn - and you learn by articulating what makes documentation clear. + +### Learning Pattern Used in This Chapter + +1. Install and configure the tool before starting the task. +2. Practice on someone else's work first (reviewing is safer than authoring). +3. Use accessibility tools (`F7` Accessible Diff Viewer) to navigate efficiently. +4. Write specific, constructive feedback (not just "looks good"). + + +## Table of Contents + +1. [Installing the GitHub Pull Requests Extension](#1-installing-the-github-pull-requests-extension) +2. [Viewing Pull Requests](#2-viewing-pull-requests) +3. [Checking Out a Pull Request Branch](#3-checking-out-a-pull-request-branch) +4. [Reviewing Pull Requests in VS Code](#4-reviewing-pull-requests-in-vs-code) +5. [Creating a Pull Request from VS Code](#5-creating-a-pull-request-from-vs-code) +6. [Pull Request Description Templates](#6-pull-request-description-templates) +7. [Commenting and Requesting Changes](#7-commenting-and-requesting-changes) +8. [Merging Pull Requests](#8-merging-pull-requests) + + +## 1. Installing the GitHub Pull Requests Extension + +The GitHub Pull Requests and Issues extension integrates GitHub's PR workflow directly into VS Code - no browser tab switching required. + +### Installation Steps + +#### Method 1: Extensions Sidebar + +1. Open Extensions sidebar: `Ctrl+Shift+X` (Mac: `Cmd+Shift+X`) +2. Type "GitHub Pull Requests" in the search box +3. Find "GitHub Pull Requests and Issues" (publisher: GitHub) +4. Navigate to the extension in the results list +5. Press `Enter` to open the extension detail page +6. `Tab` to "Install" button → press `Enter` + +#### Method 2: Command Palette + +1. `Ctrl+Shift+P` +2. Type "install extensions" +3. Select "Extensions: Install Extensions" +4. Search for "GitHub Pull Requests" +5. Install "GitHub Pull Requests and Issues" + +**Screen reader note:** The Extensions sidebar is a tree view. Use `Up/Down Arrow` to navigate, `Enter` to open an extension's detail page. + +### Signing In to GitHub + +After installation, VS Code prompts you to sign in: + +1. A notification appears: "Sign in to GitHub to use Pull Requests" +2. Navigate to the notification (`Alt+N` / Mac: `Option+N`, or status bar navigation) +3. Select "Sign in" +4. VS Code opens your browser for GitHub OAuth authentication +5. Authorize VS Code in the browser +6. Return to VS Code - you're now signed in + +#### Verify sign-in + +- Open Command Palette: `Ctrl+Shift+P` (Mac: `Cmd+Shift+P`) +- Type "GitHub Pull Requests: Sign in" +- If already signed in, the option shows "Sign out" instead + +### What the Extension Adds + +After installation, you gain: + +- **GitHub view in the Activity Bar** (sidebar icon that looks like the GitHub logo) +- **Pull Requests and Issues tree** in the Explorer +- **PR creation commands** in the Command Palette +- **Inline PR review features** in the editor +- **Issue linking** when writing commit messages + +### Learning Cards: Installing the PR Extension + +
    +Screen reader users + +- Open Extensions with `Ctrl+Shift+X`, type "GitHub Pull Requests" -- your screen reader announces each result; press `Enter` on the correct one then `Tab` to "Install" +- After installation, verify sign-in via Command Palette (`Ctrl+Shift+P`): type "GitHub Pull Requests: Sign in" -- if already signed in, it shows "Sign out" instead +- The GitHub view appears as a new icon in the Activity Bar; press `F6` to cycle between panels until you hear "GitHub" + +
    + +
    +Low vision users + +- A new GitHub logo icon appears in the Activity Bar (left sidebar) after installation -- it is the Octocat silhouette +- After signing in, the notification bar at the bottom confirms authentication with your username +- Increase sidebar width by dragging its edge so PR titles are not truncated at high zoom levels + +
    + +
    +Sighted users + +- Look for the GitHub Octocat icon in the Activity Bar after installation -- click it to open the Pull Requests and Issues panel +- A blue notification badge appears on the icon when there are new PRs to review +- The Explorer sidebar also gains a "GitHub Pull Requests" section that you can expand or collapse + +
    + + +## 2. Viewing Pull Requests + +### Opening the GitHub Pull Requests Panel + +#### Method 1: Activity Bar + +
    +Visual / mouse users + +Click the **GitHub logo icon** in the Activity Bar (the vertical strip of icons on the far left). It's usually the 5th or 6th icon. The GitHub Pull Requests panel opens. + +
    + +
    +Screen reader users (NVDA / JAWS / VoiceOver) + +1. The Activity Bar is not always reachable by `Tab` from the editor +2. Use `Ctrl+Shift+P` (Mac: `Cmd+Shift+P`) → type "GitHub Pull Requests: View Pull Request" or "Focus on Pull Requests View" → press `Enter` +3. Alternatively press `Ctrl+Shift+G` (Mac: `Cmd+Shift+G`) to open Source Control, then `Tab` until you reach the Activity Bar icon strip + +The GitHub view opens, showing: + +- "Pull Requests" +- "Issues" + +
    + +
    +Web alternative (github.com) + +View pull requests directly on GitHub without VS Code: + +1. Navigate to the repository on GitHub.com +2. Click the **Pull requests** tab +3. Click any PR title to view its conversation, commits, and changed files +4. Use the **Files changed** tab to review diffs + +See [Working with Pull Requests](06-working-with-pull-requests.md) for the full web-based PR workflow. + +
    + +
    +GitHub CLI (gh) alternative + +View PRs from your terminal: + +```bash +# List open PRs +gh pr list + +# View a specific PR +gh pr view 42 + +# Open a PR in your browser +gh pr view 42 --web + +# Filter PRs waiting for your review +gh pr list --search "review-requested:@me" +``` + +
    + +## Method 2: Explorer Section + +1. Open Explorer: `Ctrl+Shift+E` (Mac: `Cmd+Shift+E`) +2. Navigate with `Arrow` keys to find the "GitHub Pull Requests" section +3. Expand it with `Right Arrow` + +### Pull Request Tree Structure + +#### Description + +The GitHub Pull Requests panel has two top-level sections. "My Pull Requests" contains four filters: Assigned to Me, Created by Me, Waiting for my Review, and All Open. The repository section shows Local Pull Request Branches (checked out locally), All Open Pull Requests, and All Closed Pull Requests. + +#### Screen reader announcement example + +"Pull Request #42: Add Timeline Guide, opened by jeffb, 2 days ago, 3 files changed" + +### Filtering PR Lists + +#### By status + +- "All Open" - every open PR +- "Assigned to Me" - PRs where you're an assignee +- "Waiting for my Review" - PRs where you're requested as reviewer +- "Draft" - PRs marked as work-in-progress + +#### By repository + +The tree organizes PRs by repository. Expand a repo to see its PRs. + +### Viewing PR Details + +1. Navigate to a PR in the tree +2. Press `Enter` + +A PR detail view opens in the editor area showing: + +- PR title and number +- Author and creation date +- Status (Open, Merged, Closed) +- Description (full Markdown with inline rendering) +- Reviewers and their status (Approved, Requested Changes, Pending) +- Checks (CI status: passing, failing, pending) +- Files changed (clickable list) +- Comments timeline + +#### Screen reader experience + +- The detail view is Markdown-rendered HTML +- Use standard screen reader reading commands (`Arrow` keys in NVDA/JAWS virtual mode) +- Headings mark each section ("Description", "Reviewers", "Files Changed", "Comments") +- Links are clickable with `Enter` + + +## 3. Checking Out a Pull Request Branch + +**Checking out a PR** means downloading its branch to your local machine so you can test it, review it interactively, or add commits to it. + +### Why Check Out a PR + +- **Test functionality:** Run the code locally to verify it works +- **Review with full context:** See the changes in your editor with full file access +- **Make suggestions:** Add commits to someone else's PR (if you have write access) +- **Verify accessibility:** Test with your screen reader to ensure changes don't break navigation + +### How to Check Out a PR + +#### Method 1: From the PR Detail View + +1. Open a PR (see Section 2) +2. In the PR detail view, navigate to "Checkout" button +3. Press `Enter` + +VS Code: + +- Downloads the branch +- Switches your local repository to that branch +- Opens the changed files in the editor + +#### Method 2: From the PR Tree + +1. Navigate to the PR in the GitHub Pull Requests tree +2. Press `Shift+F10` (Mac: `Ctrl+Return`) to open context menu +3. Select "Checkout Pull Request" + +#### Method 3: Command Palette + +1. `Ctrl+Shift+P` (Mac: `Cmd+Shift+P`) +2. Type "GitHub Pull Requests: Checkout" +3. Select "GitHub Pull Requests: Checkout Pull Request" +4. Choose the PR from the list + +**Screen reader note:** After checkout, the bottom-left status bar shows the branch name (example: "jeffb/add-timeline-guide"). Your local files now match that branch. + +### Returning to Your Original Branch + +After reviewing: + +1. `Ctrl+Shift+P` (Mac: `Cmd+Shift+P`) +2. Type "git checkout" +3. Select "Git: Checkout to..." +4. Choose your original branch (usually `main` or your feature branch) + +### Learning Cards: Checking Out a PR + +
    +Screen reader users + +- After checkout, press `F6` to navigate to the Status Bar and hear the branch name (e.g., "jeffb/fix-alt-text") confirming you are on the PR branch +- Use `Ctrl+Shift+P` then "Git: Checkout to" to switch back to your original branch when done reviewing +- The PR detail view is Markdown-rendered HTML -- navigate with `h` (heading), `t` (table), and arrow keys in your screen reader's virtual mode + +
    + +
    +Low vision users + +- The Status Bar in the bottom-left changes to show the PR branch name, confirming the checkout succeeded +- Files changed by the PR are highlighted in the Explorer sidebar with colored badges (M for modified, A for added) +- Use `Ctrl+=` to zoom the editor if diff annotations are hard to read + +
    + +
    +Sighted users + +- After checkout, the branch name in the bottom-left Status Bar changes to the PR branch name +- Changed files appear in the Source Control panel with status badges so you can quickly see what was modified +- Right-click a file in the PR file list to open a side-by-side diff view + +
    + + +## 4. Reviewing Pull Requests in VS Code + +Once you've checked out a PR (or opened it in the detail view), you can review its changes fully within VS Code. + +### Reading the Files Changed List + +#### In the PR detail view + +1. Scroll down to "Files Changed" section +2. Each file is a link +3. Navigate with `Arrow` keys +4. Press `Enter` on a file to open its diff view + +#### Screen reader announcement + +"docs/11-vscode-interface.md, 42 additions, 3 deletions" + +### Understanding the Diff View + +When you open a file from "Files Changed": + +#### Split view mode (default) + +- Left side: original file (before changes) +- Right side: modified file (after changes) +- Changed lines highlighted (added = green, removed = red) + +#### Inline view mode + +- Single editor +- Removed lines shown with `-` prefix +- Added lines shown with `+` prefix + +#### To toggle between views + +- Command Palette: `Ctrl+Shift+P` (Mac: `Cmd+Shift+P`) → "Diff: Toggle Inline View" + +### Screen Reader Diff Review with Accessible Diff Viewer + +#### Recommended workflow for screen reader users + +1. Open a changed file from the PR detail view +2. Press `F7` to jump to the first diff hunk +3. Press `Alt+F2` (Mac: `Option+F2`) to open Accessible View +4. Read the hunk content: + - Unchanged lines (for context) + - Removed lines (prefixed with `-`) + - Added lines (prefixed with `+`) +5. Press `Escape` to close Accessible View +6. Press `F7` to jump to the next hunk +7. Repeat until all hunks reviewed + +#### Example Accessible Diff output + +```text +Hunk 1 of 3 - lines 12 to 18 + Unchanged: ## VS Code Setup +- Removed: This guide covers VS Code basics. ++ Added: This guide covers VS Code basics and accessibility features. + Unchanged: + Unchanged: **Prerequisites:** Day 1 completion +``` + +#### This structured reading is far superior to navigating the visual diff manually +> +> **VS Code October 2025 update:** Deleted lines (shown with the `-` prefix) are now fully selectable and copyable in the diff editor. Previously, deleted code could only be read, not selected. This is useful when you want to copy a deleted function signature, old variable name, or removed text for reference while writing your review comment. + +### Flagging Issues During Review + +As you review, note any problems: + +1. Navigate to the specific line in the diff +2. Press `Shift+F10` (Mac: `Ctrl+Return`) for context menu +3. Select "Add Comment" +4. Type your comment in the input that appears +5. Choose "Single Comment" or "Start Review" + +**Single Comment** posts immediately. +**Start Review** saves your comments as a draft until you submit the full review (see Section 7). + +### Learning Cards: Reviewing Pull Requests in VS Code + +**Screen reader users:** +- Press `F7` to enter the Accessible Diff Viewer and hear each hunk announced as "Change N of M" with clear "Removed:" and "Added:" labels -- this is far more reliable than navigating the raw split diff line by line +- After reviewing a hunk, press `Escape` to return to the diff editor, then `Shift+F10` on the target line and select "Add Comment" to place inline feedback exactly where the issue is +- Use `Alt+F2` (Accessible View) on any hunk for a plain-text rendering you can read with arrow keys at your own pace + +**Low-vision users:** +- Switch from split diff to inline diff (`Ctrl+Shift+P` then "Toggle Inline View") to keep all changes in a single column -- much easier at high zoom than scanning two narrow panes +- Press `F7` / `Shift+F7` to jump between hunks; each hunk gains a visible focus outline that tracks your position so you do not lose your place at high magnification +- Added lines show a green gutter bar and removed lines a red gutter bar; in High Contrast themes these become bold solid borders visible at any zoom level + +**Sighted users:** +- Scan the left gutter for green (added) and red (removed) bars to spot changes quickly, then click the `+` icon on any line to start an inline comment +- Use the minimap on the right edge of the diff editor to see the distribution of changes across the file and click directly on coloured blocks to jump there +- Right-click a file in the PR file list and choose "Open Changes" for a side-by-side diff, or "Open File" to see the final state without diff annotations + + +## 5. Creating a Pull Request from VS Code + +### Tool Cards: Create a Pull Request (from your editor) + +**VS Code Desktop (primary for Day 2):** +1. `Ctrl+Shift+P` > **GitHub Pull Requests: Create Pull Request**. +2. Fill in the title, description, and base branch. +3. Click **Create**. + +**github.com (browser):** +1. Push your branch, then click the **Compare & pull request** banner on the repo page. +2. Fill in the form and click **Create pull request**. + +**GitHub Desktop:** +1. After pushing, click **Create Pull Request** -- this opens gitub.com with the form pre-filled. + +**Git CLI / GitHub CLI:** +```bash +git push -u origin your-branch +gh pr create --title "Title" --body "Description" +``` + +After you've pushed commits to a feature branch, you can create a PR without leaving VS Code. + +### Prerequisites + +1. You've created a branch (see [Git & Source Control: Branch Management](14-git-in-practice.md#3-branch-management)) +2. You've made commits +3. You've pushed the branch to GitHub (`Ctrl+Shift+P` / Mac: `Cmd+Shift+P` → "Git: Push") + +### Creating the PR + +#### Method 1: Command Palette (Recommended) + +1. `Ctrl+Shift+P` (Mac: `Cmd+Shift+P`) +2. Type "GitHub Pull Requests: Create" +3. Select "GitHub Pull Requests: Create Pull Request" +4. A form opens in the editor + +#### Method 2: Source Control Panel + +1. Open Source Control: `Ctrl+Shift+G` (Mac: `Cmd+Shift+G`) +2. After pushing, a "Create Pull Request" button appears +3. Press `Enter` on that button + +#### Method 3: GitHub Panel + +1. Open GitHub view (Activity Bar → GitHub icon) +2. Right-click your branch in the tree +3. Select "Create Pull Request" + +### Filling Out the PR Form + +The form has these fields: + +#### Title (required) + +- Auto-filled with your most recent commit message +- Edit to make it descriptive (example: "Add Timeline View documentation") + +#### Description (optional but recommended) + +- Explain what changed and why +- Reference the issue you're fixing: "Fixes #42" +- If a PR template exists, VS Code loads it here (see Section 6) +- **Copilot-assisted description:** An AI sparkle icon in the description toolbar lets you generate a description from your commits. When a PR template exists, Copilot fills in the template sections intelligently rather than replacing the template - it populates the checklist items and description sections with content derived from your changes. + +#### Base branch (target) + +- Usually `main` or `develop` +- This is the branch your changes will merge into + +#### Compare branch (source) + +- Your feature branch (auto-selected) +- This is the branch with your changes + +#### Reviewers (optional) + +- Select people to review your PR +- Navigate the list with `Arrow` keys + +#### Labels (optional) + +- Add labels like `documentation`, `accessibility`, `good-first-issue` + +#### Milestone (optional) + +- Link the PR to a project milestone + +#### Draft PR checkbox + +- Check this if the PR is not ready for review yet +- Unchecked = "Ready for review" + +#### Screen reader navigation + +- All fields are standard form inputs +- `Tab` to move between fields +- Use `Arrow` keys in dropdowns (reviewers, labels, milestones) + +### Submitting the PR + +1. Review all fields +2. `Tab` to "Create" button +3. Press `Enter` + +VS Code creates the PR on GitHub and shows a success message. The PR link appears in the notification - click it to open the PR on GitHub, or open it in the GitHub Pull Requests panel. + +
    +Web alternative (github.com) - creating a PR + +Create a PR from your browser after pushing your branch: + +1. Navigate to the repository on GitHub +2. If you recently pushed, a yellow banner "Compare & pull request" appears - click it +3. Otherwise: click **Pull requests** tab, then **New pull request**, then select your branch +4. Fill in the title and description +5. Click **Create pull request** + +See [Working with Pull Requests - Opening a PR](06-working-with-pull-requests.md#opening-a-pull-request) for detailed screen reader steps. + +
    + +
    +GitHub CLI (gh) alternative - creating a PR + +```bash +# Interactive: prompts for title, body, base branch +gh pr create + +# Inline: provide details directly +gh pr create --title "Add Timeline View documentation" --body "Fixes #42" + +# Create as draft +gh pr create --draft + +# Open the form in your browser +gh pr create --web +``` + +
    + +### Learning Cards: Creating a Pull Request + +
    +Screen reader users + +- Press `Ctrl+Shift+P` then type "GitHub Pull Requests: Create" -- the PR creation form opens with title, description, base branch, and reviewer fields navigable with `Tab` +- The description field supports full Markdown -- use `Ctrl+F` to find and replace `` placeholders in templates +- After creating, your screen reader announces the new PR number; the PR detail view opens automatically + +
    + +
    +Low vision users + +- The PR creation form appears as a new editor tab with clearly labeled input fields for title, description, base branch, and reviewers +- Use `Ctrl+=` to zoom the form if the input fields are small; the form reflows to accommodate larger text +- The base branch dropdown is near the top of the form -- verify it shows `main` (or your target branch) before submitting + +
    + +
    +Sighted users + +- Click the "Create Pull Request" button in the Source Control panel header (appears when you have unpushed changes on a feature branch) +- The PR form shows a preview pane for your Markdown description so you can verify formatting before submitting +- Use the reviewer picker to search for and add specific GitHub users to request reviews + +
    + + +## 6. Pull Request Description Templates + +Many repositories include a **PR template** - a Markdown file that pre-fills the PR description with a checklist or structure. + +### Where Templates Are Stored + +Common locations: + +- `.github/pull_request_template.md` (root) +- `.github/PULL_REQUEST_TEMPLATE.md` +- `.github/PULL_REQUEST_TEMPLATE/` (folder with multiple templates) +- `docs/pull_request_template.md` + +When you create a PR in VS Code, the extension automatically loads the template into the description field. + +### Example PR Template + +```markdown +## Description + + +## Related Issue + + +## Type of Change +- [ ] Bug fix +- [ ] New feature +- [ ] Documentation update +- [ ] Accessibility improvement + +## Testing + + +## Checklist +- [ ] My code follows the project's style guidelines +- [ ] I have tested with a screen reader (NVDA, JAWS, or VoiceOver) +- [ ] I have updated the documentation +- [ ] All new and existing tests pass +- [ ] I have linked this PR to the related issue + +## Screenshots (if applicable) + +``` + +### Filling Out a Template + +#### Screen reader workflow + +1. Create PR (Method 1-3 from Section 5) +2. The description field is pre-filled with the template +3. Navigate through the template with `Arrow` keys +4. Replace each `` with your content +5. Check checkboxes by typing `x` between the brackets: `- [x]` + +**Keyboard tip:** Use `Ctrl+F` (Mac: `Cmd+F`) to jump to each ` +``` + +Type this comment, press `Enter`, and Copilot drafts content based on your instruction. You review, edit, and refine. + +#### Example prompts for this workshop + +```markdown + + + + + + + +``` + +### Disabling Inline Suggestions + +If suggestions are distracting: + +
    +Visual / mouse users + +#### Temporarily disable for current language + +- Click the Copilot icon in the status bar (bottom-right `><` icon) +- Select "Disable Completions for [language]" + +#### Permanently disable completions + +- Open Settings: `Ctrl+,` (Mac: `Cmd+,`) → search "Copilot enable" → uncheck "Enable Inline Suggestions" + +
    + +
    +Low vision users + +The Copilot status bar icon (`><`) can be tiny at standard DPI. Use the Command Palette approach instead: + +- `Ctrl+Shift+P` → type "Copilot: Toggle Completions" → press `Enter` +- This toggles inline suggestions on/off without needing to find a small icon. + +
    + +
    +Screen reader users (NVDA / JAWS / VoiceOver) + +#### Temporarily disable via Command Palette + +- `Ctrl+Shift+P` (Mac: `Cmd+Shift+P`) → type "Copilot: Disable Completions" → press `Enter` +- Or navigate to the Copilot status bar item and activate it (depends on screen reader and focus) + +#### Permanently disable via Settings + +- `Ctrl+,` (Mac: `Cmd+,`) → search "inline suggestions" → toggle off "GitHub Copilot: Enable Inline Completions" + +
    + +### Learning Cards: Inline Suggestions + +
    +Screen reader users + +- Press `Alt+]` to trigger an inline suggestion manually; your screen reader announces "Suggestion:" followed by the proposed text +- Press `Tab` to accept the suggestion or `Escape` to dismiss it -- Copilot does not insert anything until you explicitly accept +- Press `Alt+F2` to open Accessible View and read the full suggestion in a clean, navigable pane before deciding + +
    + +
    +Low vision users + +- Suggestions appear as dimmed gray "ghost text" after your cursor -- increase editor font size with `Ctrl+=` if the gray text is hard to distinguish from your real code +- Switch to a High Contrast theme (`Ctrl+Shift+P` then "Color Theme") to improve the contrast between ghost text and your actual content +- The Status Bar Copilot icon spins while generating a suggestion and stops when one is ready + +
    + +
    +Sighted users + +- Look for gray text appearing after your cursor as you type -- this is the ghost text suggestion +- Press `Tab` to accept or keep typing to ignore; press `Alt+]` / `Alt+[` to cycle through alternative suggestions +- The Copilot icon in the Status Bar shows a spinning animation while generating and stays still when idle + +
    + + +## 4. GitHub Copilot Chat - Conversational Assistance + +> **See also:** [Appendix K: Copilot Reference](appendix-k-copilot-reference.md) has the complete slash command and chat variable reference. + +Copilot Chat is a full conversation interface where you ask questions, request explanations, and have content drafted. + +### Opening Copilot Chat + +**Primary panel:** `Ctrl+Shift+I` (Mac: `Cmd+Shift+I`) + +Opens the Chat panel on the right side of VS Code. + +**Inline chat (in-file):** `Ctrl+I` (Mac: `Cmd+I`) + +Opens a chat prompt directly in the editor, anchored to your cursor. Results appear inline. Best for file-specific edits. + +**Quick Chat (floating):** `Ctrl+Shift+Alt+I` (Windows) / `Cmd+Shift+Ctrl+I` (macOS) + +Opens a floating chat dialog that doesn't take up sidebar space. + +
    +Low vision users (zoom, high contrast, enlarged fonts) + +At 200%+ zoom the Chat sidebar can squeeze the editor to a narrow column. + +- **Use Quick Chat** (`Ctrl+Shift+Alt+I`) instead of the panel - it floats over the editor and closes when you press `Escape`, so you keep your full editor width. +- **Resize the Chat panel** by dragging its left edge or pressing `Ctrl+Shift+P` and running `View: Reset Panel Size`. +- **Increase Chat font size:** Settings (`Ctrl+,`), search `chat.editor.fontSize`, and set it to match your editor font size. +- **Mode and model selectors:** At high zoom the bottom toolbar may wrap to two lines. Tab through the controls - the mode dropdown and model picker are always present even if visually cut off. + +
    + +
    +CLI users (gh copilot) + +If you prefer the terminal, `gh copilot` lets you ask Copilot questions without opening VS Code Chat at all. + +**Install the extension (one time):** + +```bash +gh extension install github/gh-copilot +``` + +**Ask a general question:** + +```bash +gh copilot suggest "How do I squash the last 3 commits?" +``` + +Copilot responds with a suggested command you can copy and run. + +**Explain a command you don't recognize:** + +```bash +gh copilot explain "git rebase -i HEAD~3" +``` + +Copilot returns a plain-language explanation. + +**When to use CLI vs Chat:** Use `gh copilot` when you are already in a terminal session and want a quick answer without switching windows. Use VS Code Chat when you need workspace context (`@workspace`), file references, or multi-turn conversations. + +
    + +### Chat Modes + +Copilot Chat has four modes, selected from a dropdown at the bottom of the Chat input area. Each mode changes how Copilot interprets your request and what it can do. + +| Mode | How It Works | Best For | +| ------ | ------------- | ---------- | +| **Ask** (default) | Conversational Q&A - Copilot explains, suggests, and answers but does not edit files directly | Questions, explanations, understanding unfamiliar code, reviewing content | +| **Edit** | You define a "working set" of files; Copilot proposes edits and shows a diff you approve or reject - nothing changes without your confirmation | Targeted, multi-file changes where you want full control | +| **Agent** | Copilot works autonomously - it decides which files to open, reads and writes code, and runs terminal commands to complete the task | Larger tasks where you want Copilot to drive end-to-end | +| **Plan** | Copilot produces a step-by-step implementation plan before writing any code; you review and approve the plan first | Complex features where you want to validate the approach before any changes are made | + +#### Switching modes + +- The mode selector is a dropdown at the **bottom of the Chat input area**, just above the text field +- Tab through the toolbar at the bottom of Chat to find it, or click on the current mode name +- Screen reader users: the mode name is announced when you focus that control; press `Space` or `Enter` to open the dropdown, then `Arrow` keys to choose + +**Recommended mode for beginners:** Start with **Ask** to learn how Copilot responds to your questions, then explore **Edit** mode for making changes with full visibility into what Copilot touches. **Agent** mode is powerful but works best once you're comfortable reviewing its output. + +> **Note:** **Plan** mode was introduced in October 2025 (VS Code 1.106) and is available as a public preview. Plan mode lets you get an AI-generated implementation plan before any code is written - useful for understanding what a complex change will involve. + +### Choosing a Model + +Copilot gives you access to AI models from OpenAI, Anthropic (Claude), Google (Gemini), xAI (Grok), and others. The **model picker** is a button at the bottom of the Chat input area, next to the mode selector, showing the current model name (e.g., "Auto" or "Claude Sonnet 4.6"). + +**When "Auto" is selected** (the default), Copilot automatically chooses the best model for each request - lighter models for quick questions, more capable models for complex reasoning. Auto mode has been generally available since December 2025. You can override it whenever you want a specific model. + +#### Quick guidance + +- **Free-tier users:** GPT-4.1 and GPT-5 mini are available at no cost and handle most everyday tasks well +- **Need deep reasoning/debugging?** Try Claude Sonnet 4.6 or GPT-5.5 (1x premium requests) +- **Running Agent mode?** GPT-5.5 or Claude Sonnet 4.6 work well for autonomous multi-step tasks +- **High cost to avoid unless needed:** Claude Opus 4.6 (3x cost) - powerful but reserve for the most demanding work + +> **Model availability changes frequently.** Facilitators will provide current guidance at the workshop. For the complete model reference including plan availability, see [Appendix K: GitHub Copilot Reference](appendix-k-copilot-reference.md). + +
    +Low vision users - finding the mode and model controls + +Both the **mode selector** and **model picker** sit in the toolbar at the bottom of the Chat input area. At 200%+ zoom they may be cropped or wrapped. + +- **Keyboard access:** From the Chat input field, press `Tab` repeatedly to move through the toolbar controls. Each control announces its current value (for example, "Ask" for the mode or "Auto" for the model). +- **Opening the dropdown:** Press `Space` or `Enter` on the control, then use `Arrow` keys to browse options. Press `Enter` to select. +- **If the controls are visually hidden at high zoom:** They are still in the Tab order. Keep pressing `Tab` past the Send button and you will reach them. +- **Alternative:** Open the Command Palette (`Ctrl+Shift+P`) and type "Copilot: Select Model" or "Copilot: Change Chat Mode" to access these controls without finding them visually. + +
    + +### Chat Interface Structure + +#### Panel layout (top to bottom) + +1. **Chat input field** (multi-line text area) + - Type your prompt here + - Press `Ctrl+Enter` (Mac: `Cmd+Enter`) or `Enter` to send + +2. **Model selector dropdown** + - Choose which AI model to use (GPT-4, Claude, etc.) + - Some models better for code, others for prose + +3. **Conversation history** + - Shows your previous prompts and Copilot's responses + - Navigate with `Up/Down Arrow` + - Each message is a separate element + +4. **Action buttons** + - "Clear Chat" - start a new conversation + - "View in Editor" - open response in a new file + +### Screen Reader Navigation in Chat + +#### NVDA/JAWS + +- Chat input is a web-based text field +- Switch to Forms Mode (`Enter` or automatic when focused) +- Type your prompt +- Press `Ctrl+Enter` to send +- Response appears in a live region (announced as it streams in) +- For complete reading: press `Alt+F2` for Accessible View + +#### VoiceOver + +- `VO+Tab` to navigate to chat input +- `VO+Shift+Down` to interact +- Type prompt, `Return` to send +- `VO+Escape` to stop interacting +- Navigate down to response area +- For complete reading: `Alt+F2` for Accessible View + +### What to Ask Copilot Chat + +#### For this workshop (non-coding examples) + +| Goal | Example Prompt | +| ------ | ---------------- | +| Understand a file | `Explain what @11-vscode-interface.md covers in plain language` | +| Improve documentation | `This section is unclear. Rewrite it for a first-time contributor using a screen reader: [paste text]` | +| Check tone | `Review this PR description for tone. Is it clear, respectful, and helpful? Suggest improvements.` | +| Draft content | `Write a section on keyboard navigation in VS Code for screen reader users` | +| Explain an error | `I got this error when trying to commit: [paste error]. What does it mean and how do I fix it?` | +| Generate alt text | `Write alt text for this image: [describe what's in the image]` | +| Create checklist | `Create an accessibility review checklist for Markdown documentation` | +| Review for accessibility | `Check this Markdown for accessibility issues: [paste content]` | + +### Using @ Mentions in Chat + +#### @ symbols let you provide context to Copilot + +| Mention | What It Does | +| --------- | ------------- | +| `@workspace` | Searches your entire workspace for context | +| `@filename.md` | References a specific file | +| `#file` | Lists files to select from | +| `#selection` | References your currently selected text | +| `#terminalLastCommand` | References the last terminal command and output | + +#### Example prompts with context + +```text +Explain what @README.md covers for a new contributor + +Review #selection for accessibility issues + +Search @workspace for all references to "screen reader mode" + +What does this error mean? #terminalLastCommand +``` + +### Using Slash Commands + +Type `/` in Copilot Chat to see available commands: + +| Command | What It Does | +| --------- | ------------- | +| `/explain` | Explains selected code or text | +| `/fix` | Suggests fixes for problems in selected code | +| `/tests` | Generates tests (for code files) | +| `/help` | Shows all available commands | +| `/clear` | Clears chat history | +| `/savePrompt` | Saves the current chat conversation as a reusable `.prompt.md` file | + +#### Example + +1. Select a block of complex Markdown +2. Open Chat: `Ctrl+Shift+I` (Mac: `Cmd+Shift+I`) +3. Type `/explain` +4. Copilot explains the structure and purpose + +### Built-in Actions via Command Palette + +Copilot registers actions directly in the Command Palette. This provides a discoverable way to use Copilot without remembering slash commands or keyboard shortcuts. + +1. Open Command Palette: `F1` or `Ctrl+Shift+P` (Mac: `Cmd+Shift+P`) +2. Type `copilot` +3. Browse the list of available actions + +Useful built-in actions include: + +| Action | What It Does | +| ------ | ------------ | +| Copilot: Explain This | Explains the selected code or text | +| Copilot: Generate Docs | Generates documentation for the selected code | +| Copilot: Generate Tests | Creates test cases for the selected code | +| Copilot: Fix This | Suggests a fix for the selected code | +| Copilot: Review and Comment | Reviews selected code and adds comments | + +> **Screen reader tip:** After pressing `F1` and typing `copilot`, use `Down Arrow` to browse the filtered list. Your screen reader announces each action name. Press `Enter` to run the selected action on your current selection. + +### Learning Cards: Copilot Chat + +
    +Screen reader users + +- Open Copilot Chat with `Ctrl+Shift+I` (Mac: `Cmd+Shift+I`) -- focus lands in the chat input box, ready for your question +- After the response finishes streaming, press `Alt+F2` to open Accessible View and read the complete response with arrow keys, one paragraph at a time +- Use `@workspace` before your question to give Copilot context about your entire project (e.g., "@workspace what files reference heading levels?") + +
    + +
    +Low vision users + +- The Chat panel opens on the right side of VS Code; drag its border to make it wider for easier reading at high zoom +- Code blocks in Chat responses have a "Copy" button and an "Insert at Cursor" button at the top-right corner of each block +- Use Accessible View (`Alt+F2`) to read responses at your configured editor font size instead of the Chat panel's smaller default + +
    + +
    +Sighted users + +- Click the Copilot icon in the Activity Bar sidebar or use `Ctrl+Shift+I` to open the Chat panel +- The mode picker dropdown at the top of Chat lets you switch between Ask, Edit, and Agent modes +- Code blocks in responses have hover-revealed buttons: Copy, Insert at Cursor, and Run in Terminal + +
    + + +## 5. Copilot Edits — Making Multi-File Changes + +> **Edit mode is being deprecated.** As of VS Code 1.118 (April 2026), the separate **Edit** chat mode is being merged into **Agent mode**. Agent mode now supports the same working-set diff workflow that Edit mode provided. If you do not see an "Edit" mode option in your Chat panel, use Agent mode instead - the workflow is nearly identical. The deprecation is rolling out gradually; facilitators will confirm current behavior at the workshop. + +Copilot Edits is the **Edit** chat mode. Instead of just answering questions, Copilot proposes actual file changes — shown as a diff — across multiple files at once. You review every change before anything is saved. + +**When to use it:** +- Renaming something used across many files +- Updating documentation to match a code change +- Adding the same pattern (e.g., error handling, a header comment) to multiple files +- Refactoring a section while keeping full control of what changes + +### How to use Copilot Edits + +1. Open Copilot Chat: `Ctrl+Shift+I` (Mac: `Cmd+Shift+I`) +2. At the bottom of the Chat panel, click the **mode dropdown** and select **Edit** +3. Add files to your **working set** — these are the files Copilot is allowed to edit: + - Click **"Add Files..."** above the chat input, or + - Type `#` in the chat input and select a file from the picker, or + - Right-click a file in the Explorer and choose **"Add File to Copilot Edits"** +4. Type your request: *"Update all headings in these files to use sentence case"* or *"Add a screen reader tip callout to each section that has keyboard shortcuts"* +5. Press `Enter` — Copilot shows a diff of proposed changes in each file +6. Review the changes: use **Accept** or **Reject** on individual files, or **Accept All** / **Reject All** + +> **Nothing changes until you accept.** Copilot Edits shows you the full diff first. You are always in control. + +### Navigating the diff with a screen reader + +- Each changed file appears in the Chat panel as a collapsible section — Tab to it, press `Space` to expand +- Press **Accept** or **Reject** buttons (announced with the file name) to decide per file +- To review the changes line by line before deciding: the diff opens in the editor with `+` and `-` lines — navigate with `Arrow` keys in the terminal or diff view + +### Working set tips + +- Start with a **small working set** (2–3 files) to see how Copilot interprets your request before expanding to the full project +- You can add or remove files from the working set mid-conversation +- Copilot will tell you if it needs a file that isn't in the working set — add it and ask again + +### Learning Cards: Copilot Edits + +
    +Screen reader users + +- Copilot Edits shows proposed changes as diffs -- use `F7` in the diff view to step through hunks with announced change types (added, removed, unchanged) +- Press `Ctrl+Shift+P` then "Accept" or "Discard" to confirm or reject each proposed edit; nothing is saved until you explicitly accept +- Review each file's diff individually with arrow keys before accepting to ensure Copilot did not introduce errors + +
    + +
    +Low vision users + +- Proposed changes appear as standard diff views with green/red highlighting for added/removed lines +- Start with a small working set (2-3 files) so the diff review is manageable at high zoom +- The accept/discard buttons appear at the top of the diff view pane and remain visible as you scroll through changes + +
    + +
    +Sighted users + +- Look for a multi-file list in the Chat panel showing every file Copilot wants to change -- click each to see the proposed diff +- Green highlighted lines = additions, red highlighted lines = deletions, just like a normal Git diff +- Use the "Accept" and "Discard" buttons at the top of the diff to control changes file by file + +
    + +--- + +## 6. Agent Mode — Let Copilot Drive + +> **See also:** [Chapter 19: Accessibility Agents](19-accessibility-agents.md) and [Chapter 20: Build Your Agent](20-build-your-agent.md) for creating your own Copilot agent. + +Agent mode is the most autonomous way to use Copilot. You describe a goal and Copilot figures out what files to open, what changes to make, and what commands to run — asking for your approval when it needs to run something that has side effects. + +**When to use it:** +- Scaffolding a new feature from scratch +- Running a complex multi-step task that involves several files and commands +- Tasks where you're not sure which files need to change + +> **Agent mode is powerful — and that's worth being thoughtful about.** It can open, read, and edit files across your whole workspace and run terminal commands. Review its actions as it works, especially before approving terminal commands. Start with well-scoped tasks until you're comfortable with how it behaves. + +### How to use Agent mode + +1. Open Copilot Chat: `Ctrl+Shift+I` (Mac: `Cmd+Shift+I`) +2. Select **Agent** from the mode dropdown at the bottom of the Chat panel +3. Type your goal: *"Add a Table of Contents to every Markdown file in the docs/ folder"* or *"Find all TODO comments in this project and create a GitHub issue for each one"* +4. Copilot begins working — it shows each step it's taking and asks for approval before running terminal commands +5. Watch the progress in the Chat panel; review any proposed changes in the editor + +### Approving terminal commands + +When Agent mode wants to run a shell command (like `npm run build` or `git commit`), it pauses and shows you the command before running it. + +- **Allow** — run this command once +- **Allow Always** — always allow this command type without asking again (use carefully) +- **Cancel** — stop and don't run it + +> **Screen reader tip:** When Copilot pauses for approval, focus moves to the approval dialog in the Chat panel. Your screen reader announces the command Copilot wants to run and the approval options. Tab to your choice and press `Enter`. + +### Agent vs Edit vs Ask — choosing the right mode + +| You want to... | Use | +|----------------|-----| +| Ask a question or get an explanation | **Ask** | +| Make targeted changes to specific files you control | **Edit** | +| Complete a multi-step task and let Copilot navigate the workspace | **Agent** | +| Review and approve a plan before anything changes | **Plan** | + +--- + +### Learning Cards: Agent Mode + +**Screen reader users:** +- Agent mode's terminal command approval dialogs are announced differently by NVDA ("dialog") vs JAWS ("message box") vs VoiceOver ("alert") -- learn your screen reader's announcement so you recognize approval prompts instantly +- Listen for the confirmation prompt before any terminal command executes -- pressing Enter without reading the command is the single highest-risk action in Agent mode +- Use Accessible View (`Alt+F2`) to review the multi-step plan Agent mode proposes before approving; the plan is often too long for live region announcements to capture fully + +**Low-vision users:** +- Agent mode's progress appears in the Chat panel -- if your zoom level pushes the panel narrow, widen it or pop it out so multi-step status lines do not truncate +- Terminal command approval buttons use the same accent color as other VS Code buttons; consider a high-contrast theme so approval prompts stand out from surrounding chat text +- Watch the file tabs along the top -- Agent mode opens and edits files automatically, and new tabs appearing is your visual cue that changes are happening + +**Sighted users:** +- Agent mode is the highest-autonomy Copilot feature -- it can create files, run terminal commands, and install packages, so always read the approval dialog before clicking Continue +- The diff view after each Agent action shows exactly what changed; review diffs before moving to the next step rather than approving the entire sequence blindly +- Use the Plan step (type "plan" in Agent mode) to preview the full sequence before execution, especially for unfamiliar codebases + +--- + +## 7. Next Edit Suggestions + +Next Edit Suggestions (NES) is a feature where Copilot watches what you're editing and predicts **where you'll need to make your next change** — then offers to make it for you. Unlike regular inline suggestions that complete what you're currently typing, NES looks ahead to related edits elsewhere in the file. + +**Example:** You rename a variable on line 12. NES notices it's also used on lines 34 and 67 and offers to update those too — without you navigating there first. + +### Turning on Next Edit Suggestions + +1. Open Settings: `Ctrl+,` (Mac: `Cmd+,`) +2. Search for `nextEditSuggestions` +3. Enable **"GitHub Copilot: Next Edit Suggestions"** + +Or add to your `settings.json`: + +```json +"github.copilot.nextEditSuggestions.enabled": true +``` + +### How it works in practice + +- After making an edit, a **tab stop indicator** (an arrow `→` symbol) appears at the location of the predicted next edit +- Press `Tab` to jump there and accept the suggestion +- Press `Escape` to dismiss it and continue editing normally +- The indicator is subtle — if you don't see it, your next keystroke will proceed as normal + +> **Screen reader tip:** NES is announced as an inline suggestion at the predicted location. With screen reader optimized mode on (`Shift+Alt+F1`), VS Code announces when a next edit suggestion is available. Navigate to it with `Tab` and accept or dismiss as with any inline suggestion. + +--- + +## 8. Copilot on GitHub.com + +You don't need VS Code to use Copilot. GitHub.com has Copilot built directly into the website — useful for quick questions, reviewing code in the browser, drafting PR descriptions, and more. + +### Opening Copilot Chat on GitHub.com + +1. Go to [github.com](https://github.com) — you must be signed in +2. Look for the **Copilot icon** (a circle with dot pattern) in the top navigation bar +3. Click it (or press `?` then select Copilot from the command palette) to open the chat panel +4. Type your question and press `Enter` + +Copilot on GitHub.com has context about your repositories, issues, PRs, and code — you can reference them directly. + +### What you can ask Copilot on GitHub.com + +``` +# Ask about a specific repository +"Summarize the recent changes to the accessibility-agents repo" + +# Ask about an issue +"What are the open accessibility issues in this repo?" + +# Ask about code +"What does the auth module in this project do?" + +# General coding questions +"What's the difference between git rebase and git merge?" +``` + +### Copilot for Pull Request Summaries + +When you open a pull request on GitHub.com, Copilot can generate a description for you automatically. + +1. Start creating a new pull request: go to your branch and select **"Compare & pull request"** +2. In the PR form, look for the **Copilot icon** next to the description field +3. Click it — Copilot reads your commits and diff and writes a draft description +4. Review and edit the draft — it typically includes what changed and why +5. Submit the PR + +> **This is a huge time-saver.** Copilot-generated PR descriptions are usually a solid first draft. Always review them to add context a maintainer would need (like *why* you made the choice, not just *what* you changed). + +**Screen reader tip:** The Copilot sparkle button is next to the description textarea. It's announced as a button labelled "Copilot" or "Generate with Copilot." After clicking, the description field is populated — read through it with your screen reader before submitting. + +### Copilot for Code Review on GitHub.com + +Maintainers can use Copilot to review pull requests on GitHub.com. As a contributor, you may see **Copilot-authored review comments** on your PR — they look like regular review comments but are labelled "Copilot". + +- Copilot review comments work just like human review comments — respond, resolve, or address them +- They flag things like potential bugs, style inconsistencies, or missing edge cases +- You don't need to accept every suggestion — use your judgment + +### Copilot on GitHub.com vs VS Code + +| Feature | GitHub.com | VS Code | +|---------|-----------|---------| +| Chat (general questions) | Yes | Yes | +| Repository / issue / PR context | Yes, built in | Yes, via `@github` | +| Inline code suggestions | No | Yes | +| Copilot Edits (multi-file) | No | Yes | +| Agent mode | No | Yes | +| PR description generation | Yes | No | +| Code review comments | Yes, for maintainers | No | +| No install required | Yes | Requires extension | + +--- + +### Learning Cards: Copilot on GitHub.com + +**Screen reader users:** +- The Copilot chat icon on GitHub.com is in the site header -- navigate by landmark (`d` in NVDA/JAWS browse mode) to reach the banner, then find the button labeled "Open GitHub Copilot Chat" +- PR description generation uses a sparkle button ("Copilot actions") next to the description field -- Tab through the PR form controls to find it; it is not inside the markdown toolbar +- Browser-based Copilot Chat responses are standard page content, not a VS Code panel -- your normal web reading commands (arrows, headings, links) work without any special mode + +**Low-vision users:** +- The Copilot icon in the GitHub.com header is small (16px) -- zoom to at least 200% or use browser find (`Ctrl+F` and type "Copilot") to locate the chat entry point faster +- PR description suggestions appear inline in the description textarea; the sparkle button sits to the right of the formatting toolbar and may scroll off-screen at high zoom levels +- GitHub.com Copilot Chat opens as a side panel that overlaps page content on narrow viewports -- resize the panel or collapse the file tree to reclaim space + +**Sighted users:** +- Look for the Copilot sparkle icon in the top-right header area of any GitHub.com page to open chat; on PR pages, a second sparkle button appears next to the description field +- GitHub.com Copilot is completely separate from VS Code Copilot -- your prompts, history, and extensions do not carry over between the two environments +- Use the Copilot chat on GitHub.com for quick questions about repos, issues, and PRs without needing to clone anything locally + +--- + +## 9. Effective Prompting for Documentation Work + +Copilot works best with clear, specific prompts. The more context you provide, the better the response. + +### Anatomy of a Good Prompt + +#### Bad prompt + +```text +Write about accessibility +``` + +#### Good prompt + +```text +Write a 3-paragraph section explaining how screen reader users can navigate the VS Code Explorer sidebar. Include keyboard shortcuts for NVDA and JAWS. Assume the reader has never used VS Code before. Use clear headings and bullet points. +``` + +#### What makes it good + +1. **Specific scope:** "3-paragraph section" +2. **Clear topic:** "navigate the VS Code Explorer sidebar" +3. **Target audience:** "screen reader users" who "never used VS Code" +4. **Required details:** "keyboard shortcuts for NVDA and JAWS" +5. **Format guidance:** "headings and bullet points" + +### Prompting Patterns for This Workshop + +#### Pattern 1: Contextual Rewrite + +```text +This section is too technical for beginners. Rewrite it in plain language: + +[paste existing text] + +Target audience: Screen reader users trying VS Code for the first time +``` + +#### Pattern 2: Generate with Constraints + +```text +Write a step-by-step guide for creating a GitHub issue using only keyboard navigation. Include: +- NVDA screen reader announcements +- Exact keyboard shortcuts +- What to do if the form field is not announced correctly +Format as a numbered list +``` + +#### Pattern 3: Review and Improve + +```text +Review this PR description for: +1. Clarity for maintainers +2. Respect and positive tone +3. Whether it links to the related issue +4. If it explains WHY the change matters + +Here's the description: +[paste your PR description] +``` + +#### Pattern 4: Accessibility Audit + +```text +Check this Markdown for accessibility problems: +- Heading hierarchy (H1 → H2 → H3, no skips) +- Link text (no "click here" or bare URLs) +- Alt text for images +- List structure + +[paste Markdown content] +``` + +#### Pattern 5: Draft from Outline + +```text +Write a section based on this outline: + +## Timeline View - File History +- What Timeline shows +- How to open it (keyboard) +- How screen readers announce each commit +- How to view a specific commit's changes + +Write for screen reader users. Use H3 subheadings. Include a table for keyboard shortcuts. +``` + +### Iterating on Responses + +Copilot's first response is a draft. Refine it: + +#### Follow-up prompts + +```text +Make it shorter - reduce to 5 bullet points + +Add more detail about what NVDA announces at each step + +Rewrite this in a more friendly tone + +Add a "Common Mistakes" section at the end + +Format this as a table instead of a bulleted list +``` + +Copilot remembers the conversation context - just say what to change. + +### Learning Cards: Effective Prompting + +
    +Screen reader users + +- Include "assume the reader uses a screen reader" in your prompts to get responses with keyboard shortcuts and non-visual descriptions by default +- Ask Copilot to "use headings and bullet points" so the response is structured and easy to navigate with `Alt+F2` (Accessible View) +- Iterate by saying "make it shorter" or "add more detail about NVDA" -- Copilot retains conversation context so you do not need to repeat the original request + +
    + +
    +Low vision users + +- Ask Copilot to "include a table" when requesting reference information -- tables are often easier to scan than dense paragraphs at high zoom +- Use the "Draft from Outline" pattern: give Copilot your section headings and let it fill in the content, then review the structure before the details +- If a response is too long to review comfortably, ask "summarize in 5 bullet points" for a manageable overview + +
    + +
    +Sighted users + +- Start with a specific prompt that includes audience, format, and length requirements for better first-draft quality +- The Chat panel shows your conversation history on the left so you can return to previous prompts and refine them +- Use the "Rewrite" prompt pattern -- paste content and ask Copilot to restructure it rather than writing from scratch + +
    + + +## 10. Custom Instructions vs Custom Agents + +Two distinct tools shape how Copilot behaves. Understanding the difference is critical for working with Accessibility Agents (see [Chapter 16: Accessibility Agents](19-accessibility-agents.md)). + +### Custom Instructions + +**File:** `.github/copilot-instructions.md` + +**Purpose:** Always-on background guidance for every Copilot interaction. + +#### What they do + +- Apply to all code suggestions automatically +- Set project-wide standards +- Influence tone and style +- Provide context about your project's conventions + +#### Example `.github/copilot-instructions.md` + +```markdown +# Copilot Instructions for accessibility-agents + +## Accessibility Standards +- Include semantic HTML elements in generated markup +- Add ARIA labels to interactive components when no visible text is present +- Ensure keyboard navigation patterns are implemented for custom widgets + +## Documentation Style +- Write for screen reader users first +- Include keyboard shortcuts for NVDA, JAWS, and VoiceOver +- Use active voice and imperative mood ("Press Ctrl+G" not "You can press Ctrl+G") +- Structure content with clear headings (H2 for sections, H3 for subsections) + +## Commit Message Format +- Follow conventional commits: `type: description` +- Types: feat, fix, docs, style, refactor, test, chore +- Reference issues: "Fixes #123" + +## Tone +- Friendly but professional +- Direct and actionable +- Assume readers are competent but may be new to this specific tool +``` + +**When active:** Every time Copilot generates a suggestion (inline or in Chat) + +### You never have to ask for these - Copilot simply follows them + +### Custom Agents + +**Files:** `.github/agents/[name].agent.md` + +**Purpose:** On-demand, focused workflows that you deliberately invoke. + +#### What they do + +- Perform specific, repeatable tasks +- Can access specific tools (GitHub API, file system, terminal) +- Generate structured output (reports, reviews, analysis) +- Execute multi-step workflows + +#### Example agent names + +- `@daily-briefing` - Summarize repository activity +- `@issue-tracker` - Find and prioritize issues +- `@pr-review` - Generate PR review documentation +- `@analytics` - Team contribution metrics +- `@insiders-a11y-tracker` - Monitor accessibility changes + +**When active:** Only when you type `@agent-name` in Copilot Chat + +See [Chapter 16: Accessibility Agents](19-accessibility-agents.md) for complete agent documentation. + +### Comparison Table + +| Feature | Custom Instructions | Custom Agent | +| --- | --- | --- | +| **When active** | Background - every interaction | On-demand - you type `@agent-name` | +| **Defined in** | `.github/copilot-instructions.md` | `.github/agents/[name].agent.md` | +| **Tool access** | Standard Copilot tools | Can restrict or grant specific permissions | +| **Best for** | Broad coding standards and preferences | Focused, repeatable, specialized tasks | +| **Requires invocation** | No - always on | Yes - explicit trigger | + +### Using Both Together + +**Custom instructions** ensure Copilot follows your accessibility standards on every suggestion. + +**Custom agents** handle specific workflows like auditing, issue tracking, or automated remediation. + +#### Example workflow + +1. Your `.github/copilot-instructions.md` says: "Always check heading hierarchy in Markdown" +2. You invoke `@insiders-a11y-tracker` to scan recent changes +3. The agent finds a heading skip (H1 → H3) +4. You ask Copilot Chat to fix it: "Fix the heading hierarchy in this file" +5. Copilot's fix follows your custom instructions (uses semantic HTML, adds ARIA where needed) + +#### Both work together - instructions guide every response, agents automate specific workflows + + +### Writing Accessibility-Focused Custom Instructions + +> Source: [accessibility.github.com/documentation/guide/copilot-instructions/](https://accessibility.github.com/documentation/guide/copilot-instructions/) + +Custom instructions can be set at three levels. Each level cascades to narrower scopes: + +| Level | Where | Effect | +| ------- | ------- | -------- | +| **Organization** | Copilot organization settings | Applies to all repositories in the org | +| **Repository** | `.github/copilot-instructions.md` | Overrides org instructions; applies to one repo | +| **Personal** | GitHub.com → Settings → Copilot → Instructions | Your own preferences; highest priority | + +#### Do's - What Makes Instructions Effective + +##### Use normative language: MUST, MUST NOT, SHOULD, SHOULD NOT + +Most language models respond well to normative language. These terms reduce ambiguity and make rules clearly mandatory versus optional - the same approach WCAG itself uses: + +```text +## Keyboard Navigation +- Keyboard shortcuts SHOULD NOT override high-priority browser or OS shortcuts. +- A keyboard shortcut MUST use at most 4 simultaneous keys. +- All interactive components MUST be reachable by Tab key. +``` + +### Focus on team-specific standards, not generic principles + +Copilot already knows WCAG. Tell it what *your team* does specifically: + +```text +This application MUST conform to WCAG 2.2 Level AA. +DeprecatedButton SHOULD NOT be used; use NewAccessibleButton instead. +``` + +### Use lists and checklists to structure instructions + +Lists provide clear guardrails - Copilot follows them step by step: + +```text +## Checklist for evaluating 1.3.1 Info and Relationships +- [ ] role="presentation" MUST NOT be applied to semantic elements. +- [ ] Error messages MUST be programmatically associated with inputs. +- [ ] Name-value pairs MUST NOT use headings; use

    . +``` + +### Reference and enforce your design system + +Document which components to use and which are deprecated. Design systems evolve - keep instructions current: + +```text +Use AccessibleModal from @company/ui-kit@3.x. +LegacyDialog MUST NOT be used in any new code. +``` + +#### Don'ts - Common Instruction Mistakes + +##### Don't paste entire WCAG guidelines + +Copilot is already trained on WCAG. Pasting the full text wastes context space and dilutes your specific instructions. Instead, write concise, actionable rules that give *net-new* information: your team's specific practices, exceptions, and priorities. + +##### Don't reference external links + +By default, Copilot does not access external links in custom instructions - this is a deliberate security feature. A URL like `https://www.w3.org/WAI/WCAG21/` will not be fetched. Write the relevant rule directly. + +##### Don't reference private repositories + +Copilot cannot access private repository content from within custom instructions unless the content is already present in the active repo. + +#### Additional Guidance + +**Role-based prompting** - You can give Copilot a persona to shape how it responds: + +```text +As the lead accessibility expert on your team, your primary focus is ensuring +all UI is accessible by default, relying on semantic HTML before ARIA attributes. +``` + +Be specific about skills and responsibilities; avoid broad personas that may introduce unintended assumptions. + +**Keep instructions concise.** There is no hard character limit, but overly long instructions reduce precision. Summarize the most important, actionable rules rather than listing every possible guideline. + +**Contribute effective instructions** to [github.com/github/awesome-copilot](https://github.com/github/awesome-copilot) so others benefit from your organization's work. + +#### Accessibility Resources for Custom Instructions + +These resources can help you write better accessibility-focused custom instructions and evaluate Copilot's output: + +- **A11y LLM Evaluation Report** - GitHub's own evaluation of how well LLMs handle accessibility tasks, with practical benchmarks: [Accessibility LLM Evaluation](https://githubnext.com/projects/a11y-llm-eval) +- **Beast Mode Accessibility Prompt** - A community-maintained, comprehensive accessibility prompt that you can adapt for your own instructions: referenced in [github.com/github/awesome-copilot](https://github.com/github/awesome-copilot) +- **Markdown Accessibility Review Guidelines** - A practical guide for reviewing Markdown output for accessibility, useful as a reference when writing documentation-focused instructions: [Markdown Accessibility](https://github.com/github/accessibility/blob/main/docs/markdown-accessibility.md) + + +## 11. Using Accessible View with Copilot Responses + +Copilot Chat responses stream in token by token. This is visually nice but can fragment screen reader announcements. **Accessible View** provides complete, structured access to generated content. + +> **Not just for screen readers:** Accessible View is also valuable for low vision users. It renders text at your configured editor font size in a clean pane without the Chat panel's smaller default font, cramped layout, or streaming animation. + +### Why Use Accessible View for Copilot + +#### Without Accessible View + +- Responses announced in fragments as tokens arrive +- Live region updates may interrupt or overlap +- Difficult to re-read specific parts +- Context can be lost in streaming + +#### With Accessible View (`Alt+F2` / Mac: `Option+F2`) + +- Full complete response in a readable pane +- Navigate with `Up/Down Arrow` at your own pace +- Code blocks properly formatted +- Headings and lists structured +- No interruptions or live region noise + +### Recommended Workflow + +#### Every time you ask Copilot something + +1. Type your prompt in Chat input +2. Press `Ctrl+Enter` (Mac: `Cmd+Enter`) to send +3. Press `Alt+F2` (Mac: `Option+F2`) to open Accessible View - you can open it immediately after sending, before the response finishes +4. Follow along as the response streams in the Accessible View in real-time +5. Read or re-read any section with `Arrow` keys +6. Press `Escape` to close Accessible View and return to Chat + +> **VS Code December 2025 update:** The Accessible View now updates dynamically as responses stream in. You no longer need to wait for a response to finish before opening it - open `Alt+F2` right after sending and follow the response as it arrives. + +#### Benefits + +- Follow responses live without waiting +- Navigate and re-read at your own pace +- Code blocks and lists are properly structured +- Headings are announced correctly + +### Accessible View for Inline Suggestions + +#### When a suggestion appears + +1. Don't accept it immediately +2. Press `Alt+F2` (Mac: `Option+F2`) +3. Accessible View shows: "Suggestion: [full text of the suggestion]" +4. Read it completely +5. To insert the suggestion at your cursor: press `Ctrl+/` (Mac: `Cmd+/`) +6. To close without inserting: press `Escape`, then `Tab` to accept or `Escape` to reject + +**`Ctrl+/` (Mac: `Cmd+/`) inserts the suggestion directly from Accessible View** - you don’t need to close the view first and then press `Tab`. This is the recommended workflow for screen reader users. + +#### This is especially useful for multi-line suggestions where the ghost text is hard to review + +### Code Blocks in Accessible View + +When Copilot suggests code or Markdown: + +#### In Accessible View + +- Code blocks are in `

    ` elements
+- Screen readers announce "code block" or "pre-formatted text"
+- Each line is on its own line (not run together)
+- Indentation is preserved
+
+**NVDA/JAWS:** Use `Arrow` keys to read line by line. Use `Ctrl+Home` to jump to the start.
+
+**VoiceOver:** Interact with the code block (`VO+Shift+Down`) to read each line with proper structure.
+
+### Learning Cards: Using Accessible View with Copilot Responses
+
+**Screen reader users:**
+- Build the `Alt+F2` --> read --> `Ctrl+/` muscle memory: press `Alt+F2` to open Accessible View, read the response at your own pace with arrow keys, then press `Ctrl+/` to insert the code suggestion into your file
+- Accessible View converts Copilot's streaming markdown into a plain text buffer -- headings, lists, and code blocks are all there, but read as flat text without formatting announcements, which is often easier to parse
+- If a Copilot response contains multiple code blocks, each block starts on its own line in Accessible View -- use your search command (`Ctrl+F` in the view) to jump between code blocks quickly
+
+**Low-vision users:**
+- Accessible View opens as a separate editor pane that inherits your font size and theme -- if Copilot Chat text is too small in the sidebar, `Alt+F2` gives you the same content at your preferred zoom
+- The Accessible View pane can be resized like any editor pane; drag the border or use the keyboard layout commands to give it more horizontal space for long code lines
+- Use `Ctrl+/` from Accessible View to insert code at your cursor position without needing to copy-paste manually, reducing the chance of losing your place in the file
+
+**Sighted users:**
+- Even with full vision, `Alt+F2` is useful when Copilot Chat responses are long -- it opens the response as a full editor buffer where you can scroll, search, and select text more easily than in the Chat sidebar
+- The `Ctrl+/` shortcut (insert at cursor) works from Accessible View regardless of whether accessibility mode is on -- it is a productivity shortcut, not just an accessibility feature
+- If you ever lose track of what Copilot suggested, `Alt+F2` always shows the most recent response without scrolling through chat history
+
+
+## 12. Keyboard Shortcuts Reference
+
+### Copilot Inline Suggestions
+
+| Action | Windows/Linux | macOS |
+| --------  | ---------------  | -------  |
+| Accept suggestion | `Tab` | `Tab` |
+| Reject suggestion | `Escape` | `Escape` |
+| Accept word-by-word | `Ctrl+Right Arrow` | `Cmd+Right Arrow` |
+| Next suggestion | `Alt+]` | `Option+]` |
+| Previous suggestion | `Alt+[` | `Option+[` |
+| Open suggestions list | `Ctrl+Enter` | `Cmd+Enter` |
+| Open suggestion in Accessible View | `Alt+F2` | `Option+F2` |
+| Insert suggestion from Accessible View | `Ctrl+/` | `Cmd+/` |
+
+### Copilot Chat
+
+| Action | Windows/Linux | macOS |
+| --------  | ---------------  | -------  |
+| Open Chat panel | `Ctrl+Shift+I` | `Cmd+Shift+I` |
+| Inline chat (in-file) | `Ctrl+I` | `Cmd+I` |
+| Quick chat (floating) | `Ctrl+Shift+Alt+I` | `Cmd+Shift+Ctrl+I` |
+| Send message | `Ctrl+Enter` | `Cmd+Enter` |
+| Clear chat | `Ctrl+L` | `Cmd+L` |
+
+### Accessibility
+
+| Action | Windows/Linux | macOS |
+| --------  | ---------------  | -------  |
+| Toggle screen reader optimized mode | `Shift+Alt+F1` | `Shift+Option+F1` |
+| Open Accessible View | `Alt+F2` | `Option+F2` |
+| Open Accessible Help | `Alt+H` | `Option+H` |
+| Close Accessible View | `Escape` | `Escape` |
+
+### VS Code General (Quick Reference)
+
+| Action | Windows/Linux | macOS |
+| --------  | ---------------  | -------  |
+| Command Palette | `Ctrl+Shift+P` | `Cmd+Shift+P` |
+| Go to file | `Ctrl+P` | `Cmd+P` |
+| Find in file | `Ctrl+F` | `Cmd+F` |
+| Settings | `Ctrl+,` | `Cmd+,` |
+| Source Control | `Ctrl+Shift+G` | `Cmd+Shift+G` |
+| Explorer | `Ctrl+Shift+E` | `Cmd+Shift+E` |
+| Terminal | `Ctrl+Backtick` | `Ctrl+Backtick` |
+
+### GitHub.com Shortcuts (Not VS Code)
+
+These shortcuts work on GitHub.com in your browser, not inside VS Code. Students sometimes confuse them with Copilot shortcuts because they involve similar key combinations.
+
+| Action | Shortcut | What it opens |
+| ------ | -------- | ------------- |
+| Open github.dev web editor | `.` (period key) | A lightweight VS Code editor in your browser tab. Read-only for most operations. Copilot is **not** available here. |
+| Open in a Codespace | `,` (comma key) | A full cloud development environment with a terminal. Copilot **is** available if your account has access. |
+
+> **Ctrl+. versus the period key:** On a GitHub repository page, pressing the `.` (period) key alone opens github.dev. This is different from `Ctrl+.` inside VS Code, which opens the Quick Fix menu. If you press `Ctrl+.` on GitHub.com, it opens the GitHub Command Palette, not github.dev. These three actions share similar keys but do completely different things depending on where you press them.
+
+> **Screen reader note:** When github.dev opens, your browser tab reloads into a VS Code-like interface. Your screen reader may announce "Visual Studio Code" or "GitHub Dev Editor." This is a web page, not the desktop application. Press `Ctrl+Shift+P` to confirm you are in github.dev by reading the title bar.
+
+**Complete keyboard reference:** See [Appendix M: VS Code Accessibility Reference](appendix-g-vscode-reference.md)
+
+### Video Tutorials (Screen Reader Demonstrations)
+
+GitHub's accessibility team has published screen reader walkthroughs for each major Copilot feature. These are sourced from the official [GitHub Accessibility guide for Copilot in VS Code](https://accessibility.github.com/documentation/guide/github-copilot-vsc/):
+
+- [Inline suggestions with a screen reader](https://www.youtube.com/watch?v=nRsshE54bjk) - accepting, rejecting, and reviewing ghost text suggestions with NVDA
+- [Inline chat with a screen reader](https://www.youtube.com/watch?v=jgON0bve74w) - using `Ctrl+I` to edit code in place with screen reader feedback
+- [Chat view with a screen reader](https://www.youtube.com/watch?v=uVGLQeZWXao) - navigating the Chat panel, reading responses, and using Accessible View
+- [Built-in actions with a screen reader](https://www.youtube.com/watch?v=J0DGD2IWypg) - running Copilot commands from the Command Palette
+
+> **Tip:** These videos show NVDA with VS Code on Windows. The workflows apply to JAWS and VoiceOver with minor shortcut differences noted in each section above.
+
+
+## 13. Critically Evaluating AI Output
+
+Copilot is fast, fluent, and frequently wrong. The suggestions it produces look like they were written by someone who knows what they are doing -- and that is exactly what makes them dangerous if you accept them without thinking. This section gives you a framework for deciding what to keep, what to verify, and what to throw away.
+
+### When to Trust Copilot
+
+Copilot is at its best when it is generating code that thousands of developers have written before. You can generally trust suggestions that fall into these categories:
+
+- **Boilerplate and scaffolding** -- file headers, import statements, class constructors, standard function signatures
+- **Well-known patterns** -- iterating over arrays, reading files, formatting strings, writing basic tests
+- **Standard library usage** -- calling built-in methods with correct argument order
+- **Common syntax** -- closing brackets, finishing a loop body, completing a switch/case block
+
+In these situations Copilot is essentially autocomplete with broader context. The risk of error is low because the patterns are so widely repeated in its training data.
+
+### When to Verify
+
+Some suggestions look correct at first glance but carry hidden risks. Always read these carefully before accepting:
+
+- **Domain-specific logic** -- business rules, financial calculations, date/time math
+- **Security-sensitive code** -- authentication, authorization, input sanitization, cryptographic operations
+- **Accessibility attributes** -- ARIA roles, `alt` text, keyboard event handlers, focus management
+- **Numerical calculations** -- off-by-one errors, floating-point precision, unit conversions
+- **API usage** -- endpoint URLs, request headers, query parameters, response shapes
+- **Regular expressions** -- Copilot loves to generate regex patterns that almost work
+
+> **Screen reader tip:** When reviewing a suggestion in Accessible View (`Alt+F2`), read it line by line with `Down Arrow` rather than skimming. Copilot's mistakes are usually on individual lines, not in the overall structure.
+
+### When to Reject
+
+Delete the suggestion and write the code yourself when you see any of these:
+
+- **Fabricated APIs** -- function or method names that do not exist in the library you are using
+- **Outdated syntax** -- deprecated methods, old package versions, removed browser APIs
+- **Insecure patterns** -- SQL string concatenation, `eval()`, hardcoded secrets, disabled HTTPS verification
+- **Convention violations** -- naming styles, file organization, or patterns that contradict your project's standards
+- **Accessibility violations** -- interactive elements without keyboard handlers, missing label associations, incorrect heading hierarchy
+
+If you are not sure whether a suggestion falls into this category, verify it. When in doubt, reject.
+
+### Common Failure Modes
+
+The table below shows the kinds of mistakes Copilot makes most often. Recognizing these patterns helps you catch problems before they reach a reviewer.
+
+| Failure mode | What it looks like | Why it happens |
+| --- | --- | --- |
+| Fabricated function names | `response.getData()` on an object that has no `getData` method | Copilot blends APIs from multiple libraries into one suggestion |
+| Incorrect ARIA attributes | `role="textbox"` on a `
    ` that acts as a button | Training data includes many inaccessible websites |
+| Outdated dependency versions | `"react": "^16.8"` in a new project | Training data includes older tutorials and starter templates |
+| Plausible-but-wrong logic | A sort function that works for most inputs but fails on edge cases | The pattern matches what Copilot has seen, but the details are wrong |
+| Confidently incorrect explanations | Chat says "this function is O(n)" when it is actually O(n squared) | Copilot generates fluent text, not verified analysis |
+| Hallucinated URLs | Links to documentation pages or API endpoints that do not exist | Copilot predicts likely URLs from patterns, not from a live index |
+
+### The Verification Checklist
+
+Before you accept any non-trivial Copilot suggestion, run through these steps:
+
+1. **Does it compile or run?** -- Accept the suggestion, save the file, and check for errors in the Problems panel (`Ctrl+Shift+M`).
+2. **Does it do what I asked?** -- Read the code and confirm it matches your intent, not just your prompt.
+3. **Could I explain this to a reviewer?** -- If you cannot explain what every line does, you do not understand it well enough to keep it.
+4. **Does it match the project's conventions?** -- Check naming, formatting, file organization, and error handling against the existing codebase.
+5. **Did I check any URLs or references it generated?** -- Open every link, verify every package name, confirm every API endpoint.
+6. **Would this pass an accessibility review?** -- Run it through the checks described below.
+
+> **Screen reader tip:** Keep the Problems panel open (`Ctrl+Shift+M`) while you work with Copilot. After accepting a suggestion, press `F8` to jump to the next diagnostic. This catches syntax errors immediately.
+
+### Accessibility-Specific Concerns
+
+Copilot generates HTML and UI code based on what it has seen -- and much of the web is inaccessible. Watch for these problems in any suggestion that touches the user interface:
+
+- **Missing `alt` text** -- Copilot frequently generates `` tags with empty or missing `alt` attributes
+- **Improper heading levels** -- jumping from `
    ` to `
    `, breaking the document outline
+- **No keyboard handlers** -- `onClick` without `onKeyDown`, making elements unreachable for keyboard users
+- **Decorative ARIA** -- adding `role` or `aria-label` attributes that contradict the element's native semantics
+- **Generic link text** -- "click here" or "read more" instead of descriptive link text
+
+Always verify ARIA roles and patterns against the [APG (ARIA Authoring Practices)](https://www.w3.org/WAI/ARIA/apg/). If Copilot suggests an ARIA pattern, open the APG page for that widget and confirm the roles, states, and keyboard interactions match. See also [Chapter 12](12-vscode-accessibility.md) for accessibility verification workflows in VS Code.
+
+### The Right Mental Model
+
+Think of Copilot as a fast typist who has read a lot of code. It can reproduce patterns it has seen before, and it can combine those patterns in new ways. What it cannot do is:
+
+- **Understand your project** -- it does not know your business rules, your users, or your constraints
+- **Verify its own output** -- it cannot run the code it generates or check whether it works
+- **Stay current** -- its training data has a cutoff date, so newer APIs and libraries may be missing or wrong
+- **Reason about correctness** -- it predicts the most likely next token, not the most correct one
+
+The right relationship with Copilot is the one you have with a first draft. You would never submit a first draft without reading it, testing it, and revising it. Treat every Copilot suggestion the same way.
+
+For more on working with AI tools responsibly, see [Chapter 20](20-build-your-agent.md) on building and evaluating your own agent, and [Chapter 21](21-next-steps.md) for continued learning resources.
+
+### Learning Cards: Critically Evaluating AI Output
+
+
    
+Screen reader users
+
+- After accepting a Copilot suggestion, run `Ctrl+Shift+M` to open the Problems panel -- if new errors appear, Copilot may have introduced invalid syntax or broken links
+- Use `F8` to jump to the next error in the file and hear it announced; compare it against what Copilot changed to decide if the suggestion caused it
+- When Copilot generates Markdown, check heading levels with `Ctrl+Shift+O` (symbol outline) to verify the hierarchy was not broken
+
+
    
+
+
    
+Low vision users
+
+- After accepting a suggestion, look for red squiggles (errors) or yellow squiggles (warnings) in the editor -- these appear near lines Copilot modified
+- Use Markdown Preview (`Ctrl+Shift+V`) to visually verify that Copilot-generated content renders correctly, especially tables and links
+- Zoom in on the Problems panel (`Ctrl+Shift+M`) to read error details that reference specific line numbers
+
+
    
+
+
    
+Sighted users
+
+- Check the Problems panel (`Ctrl+Shift+M`) after accepting any suggestion -- new entries indicate Copilot may have introduced issues
+- Red underlines in the editor appear instantly on syntax errors; yellow underlines appear on warnings -- scan the changed area for these
+- Use the Source Control diff view to compare exactly what Copilot changed versus the previous version before committing
+
+
    
+
+
+## Troubleshooting
+
+### Copilot Not Suggesting Anything
+
+**Issue:** No suggestions appear as you type.
+
+#### Solutions
+
+1. Check Copilot is active: status bar icon should not be grayed out
+2. Click the Copilot icon → verify "Completions enabled"
+3. Check subscription status: `Ctrl+Shift+P` → "Copilot: Check Status"
+4. Restart VS Code
+5. Sign out and sign back in: `Ctrl+Shift+P` → "Copilot: Sign Out"
+
+### Suggestions Are Too Frequent/Distracting
+
+**Issue:** Constant interruptions from suggestions.
+
+#### Solutions
+
+1. Use word-by-word acceptance: `Ctrl+Right Arrow`
+2. Reduce screen reader verbosity (see Section 3)
+3. Use Accessible View (`Alt+F2`) to review suggestions without live announcements
+4. Disable inline suggestions temporarily: Copilot icon → "Disable Completions"
+
+### Chat Responses Not Announced
+
+**Issue:** Screen reader silent when Copilot responds.
+
+#### Solutions
+
+1. Wait for response to complete, then press `Alt+F2` for Accessible View
+2. Check ARIA live region settings in your screen reader
+3. Navigate manually to the response area with `Tab` or `Arrow` keys
+4. Use Quick Chat (`Ctrl+Shift+Alt+I`) instead of panel chat
+
+### "Copilot Subscription Required"
+
+**Issue:** Extension installed but asks for subscription.
+
+#### Solutions
+
+1. Sign in to GitHub: Copilot icon → "Sign in"
+2. Verify GitHub account has Copilot access (free tier or paid)
+3. Check [github.com/settings/copilot](https://github.com/settings/copilot) for subscription status
+4. Free tier users: ensure you haven't exceeded monthly limits
+
+
+## Try It: Your First Copilot Conversation
+
+**Time:** 3 minutes | **What you need:** VS Code with Copilot Chat extension installed
+
+1. **Open Copilot Chat** - Press `Ctrl+Shift+I` (Mac: `Cmd+Shift+I`). Your screen reader announces the chat panel.
+2. **Ask a question** - Type: `What does the CONTRIBUTING.md file in this repository say about how to submit a pull request?` Press `Enter`.
+3. **Read the response** - Press `Ctrl+Shift+A` to open the Accessible View if your screen reader doesn't read the response automatically. The response appears as plain text you can arrow through.
+4. **Try a follow-up** - Type: `Summarize that in 3 bullet points` and press `Enter`. Copilot remembers the context from your first question.
+
+**You're done.** You just had a conversation with an AI about your codebase.
+
+> **What success feels like:** Copilot answered a real question about real files in your repository. You can use this same pattern to ask about code, documentation, or anything else in the project - and the Accessible View ensures you can always read the response.
+
+---
+
+*Next: [Chapter 17: Issue Templates](17-issue-templates.md)*  
+*Back: [Chapter 15: Code Review](15-code-review.md)*  
+*Related appendices: [Appendix K: Copilot Reference](appendix-k-copilot-reference.md)*
+
diff --git a/admin/qa-bundle/docs/17-issue-templates.md b/admin/qa-bundle/docs/17-issue-templates.md
new file mode 100644
index 0000000..13c6bcf
--- /dev/null
+++ b/admin/qa-bundle/docs/17-issue-templates.md
@@ -0,0 +1,2500 @@
+# Issue Templates
+>
+> **Listen to Episode 16:** [Issue Templates](../admin/PODCASTS.md) - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned.
+
+> **Related appendices:** [Appendix Q: GitHub Actions](appendix-q-actions-workflows.md) | [Appendix C: Markdown Reference](appendix-c-markdown-reference.md) | [Appendix N: Advanced Search](appendix-n-advanced-search.md)
+> **Authoritative sources:** [GitHub Docs: About issue and PR templates](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/about-issue-and-pull-request-templates) | [GitHub Docs: Configuring issue templates](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository)
+
+
+## Structuring Contributions for Clarity and Quality
+
+> Issue templates turn a blank text box into a guided form. They help contributors provide the information maintainers need, reduce back-and-forth, and make every issue immediately actionable. This guide teaches you what templates are, how to use the ones in [accessibility-agents](https://github.com/Community-Access/accessibility-agents), and how to create your own - including an accessibility-specific bug report template.
+
+
+## Prerequisites Checklist
+
+### Before starting this chapter, verify you have completed
+
+**Hard Requirements:**
+- [ ] Chapter 4: [Working with Issues](05-working-with-issues.md) - Know how to create, read, and navigate issues
+- [ ] A GitHub repository where you have write access (your fork or personal repo)
+- [ ] A text editor with YAML syntax highlighting (VS Code, or any editor showing `.yml` files with color)
+
+**Recommended (but not blocking):**
+- [ ] Chapter 16: [GitHub Copilot](16-github-copilot.md) - Optional but helpful for generating template variations
+- [ ] Chapter 10: [Notifications](10-notifications-and-day-1-close.md) - Basic understanding of workflow triggers
+- [ ] Terminal/Command line basic comfort (useful but you can GitHub web editor if needed)
+
+**What you already have:**
+- [ ] You filled out the **Workshop Registration template** to join this workshop - this is your learning tool for Chapter 17
+
+**Day 2 Amplifier:** In [Chapter 19 (Accessibility Agents)](19-accessibility-agents.md), you'll use `@template-builder` to automate template creation. Complete this chapter first, then come back to Chapter 19.
+
+**Estimated time for this chapter:** 2-2.5 hours (including exercises and YAML troubleshooting time)
+
+
+## Workshop Recommendation (Chapter 17 / Challenge 14)
+
+Chapter 17 is a **template design and implementation chapter** focused on structuring contributions with a concrete, familiar example. It supports Challenge 14: Template Remix.
+
+- **Challenge count:** 2-3 guided challenges (+ 1 optional)
+- **Automation check:** none (template structure quality is design-focused)
+- **Evidence:** issue comment or PR with template remixed or created
+- **Pattern:** analyze, remix, create, test
+
+### Challenge 14 Set
+
+1. **Analyze the registration template** - understand how the template you already filled out works.
+2. **Remix the registration template** - adapt it for a new use case (bug report, event, research).
+3. **Create a Markdown template** (optional) - build a Markdown-based template from scratch.
+4. **Test in the template chooser** (optional) - verify your template appears and works.
+
+### Challenge 14.1 Step-by-Step: Analyze the Registration Template
+
+**Goal:** Understand how professional YAML form templates work by examining the one you filled out to register for this workshop.
+
+**Where you are working:** GitHub.com - reading the template file in the [git-going-with-github](https://github.com/Community-Access/git-going-with-github) repository.
+
+**Estimated time:** 10-15 minutes.
+
+**The Template:** [`.github/ISSUE_TEMPLATE/workshop-registration.yml`](https://github.com/community-access/git-going-with-github/blob/main/.github/ISSUE_TEMPLATE/workshop-registration.yml) - This is the form you filled out to register. It is a real, production template.
+
+1. Open the template file on GitHub.com (use the link above).
+2. Read the **YAML frontmatter** (top 5 lines) and identify:
+   - `name` - what appears in the template chooser
+   - `description` - helper text when users pick this template
+   - `title` - auto-fills the issue title
+   - `labels` - automatically adds labels to issues created with this template
+3. Read the **field types** in the `body` section. Note the four types used:
+   - `type: markdown` - display-only text (instructions)
+   - `type: input` - single-line text field (name, email)
+   - `type: dropdown` - list of options (proficiency level, screen reader choice)
+   - `type: textarea` - multi-line text (questions/accommodations)
+4. For each field, identify the **metadata**:
+   - `id` - internal identifier (does not display to user)
+   - `label` - what the user sees as the field name
+   - `description` - helper text explaining what to fill in
+   - `placeholder` - example text inside the field
+   - `validations: required: true` - marks a field as required
+5. Search the file for "accessible" - notice the description mentions that all fields work with screen readers. This is professional template thinking.
+6. Compare: how is this different from a blank issue? A blank issue is a massive empty text box with no guidance. This template provides structured fields, helpful descriptions, and required/optional clarity.
+
+**You are done when:** You can explain the purpose of each field type and why templates reduce back-and-forth questions.
+
+### Challenge 14.2 Step-by-Step: Remix the Registration Template
+
+**Goal:** Adapt the registration template for a different use case while keeping the same YAML structure.
+
+**Where you are working:** VS Code with a repository where you have write access (your fork or personal repo), or github.dev.
+
+**Estimated time:** 20-30 minutes.
+
+Use this worked example as a guide:
+- **Source:** [`.github/ISSUE_TEMPLATE/workshop-registration.yml`](../.github/ISSUE_TEMPLATE/workshop-registration.yml)
+- **Remix sample:** [`learning-room/docs/samples/challenge-14-registration-remix-example.yml`](../learning-room/docs/samples/challenge-14-registration-remix-example.yml)
+
+What changes and what stays the same:
+- Keep: the YAML skeleton (`name`, `description`, `title`, `labels`, `body`)
+- Keep: field structure (`type`, `id`, `attributes`, `validations`)
+- Change: context-specific content (labels, field names, descriptions, options)
+- Re-evaluate: which fields must be required
+
+Steps:
+
+1. Pick a new context for your template (for example: bug report, event attendance, product research, accessibility audit request).
+2. Copy the registration template file to a new file: `.github/ISSUE_TEMPLATE/my-template.yml`
+3. Change the `name` and `description` in the frontmatter to match your new context.
+4. Change the `title` prefix (for example: `[Bug Report]: ` or `[Event]: `).
+5. Change the `labels` to appropriate labels for your use case.
+6. Replace each field's `label`, `description`, `placeholder`, and options to match your new context.
+7. Decide which fields should be `required: true` and which can be optional.
+8. Validate your YAML syntax: copy the file contents to [yamllint.com](https://www.yamllint.com/) and fix any errors.
+9. Commit and push to your repository.
+
+**You are done when:** Your remixed template file is committed and the YAML syntax validates without errors.
+
+### Challenge 14.3 (Optional) Step-by-Step: Create a Markdown Template
+
+**Goal:** Create a Markdown-based template to compare the two template formats.
+
+**Where you are working:** VS Code with a repository where you have write access.
+
+1. Create a new file: `.github/ISSUE_TEMPLATE/my-markdown-template.md`
+2. Add the Markdown template frontmatter at the top:
+
+```yaml
+---
+name: "My Template Name"
+about: "Short description of when to use this template"
+title: "[PREFIX]: "
+labels: documentation
+---
+```
+
+3. Note: Markdown templates use `about` instead of `description` (unlike YAML form templates).
+4. Below the frontmatter, add 3-4 sections with HTML comment instructions:
+
+```markdown
+## Problem
+
+
+## Context
+
+
+## Solution Ideas
+
+```
+
+5. Commit and push.
+
+**You are done when:** Your Markdown template file is committed with proper frontmatter and section structure.
+
+### Challenge 14.4 (Optional): Test in the Template Chooser
+
+1. Navigate to your test repository on GitHub.com.
+2. Activate **New Issue**.
+3. Verify your template appears in the template chooser.
+4. Activate **Get started** on your template and file a test issue.
+
+**You are done when:** Your template works and appears in the GitHub template picker.
+
+### Completing Challenge 14: Submit Your Evidence
+
+Open your **assigned Challenge 14 issue** and post a completion comment:
+
+```text
+Challenge 14 completed:
+- Analyzed registration template: yes / no
+- Remixed template context: [your chosen context]
+- YAML validates: yes / no
+- Template committed to: [repo name]
+- Optional Markdown template: yes / no
+- Template chooser test: yes / no
+```
+
+Close your Challenge 14 issue when done.
+
+### Expected Overall Outcomes
+
+- Student understands template structure (YAML frontmatter, field types, validation).
+- Student can analyze and remix professional templates.
+- Student can create both YAML form and Markdown templates.
+- Student understands why templates improve contribution quality.
+- Student can reduce maintainer effort through clear, guided contribution processes.
+
+### If You Get Stuck
+
+1. Cannot find the registration template? Look in `.github/ISSUE_TEMPLATE/workshop-registration.yml` in the [git-going-with-github](https://github.com/Community-Access/git-going-with-github) repository.
+2. YAML syntax confusing? The registration template is a working example. Copy its structure and edit the field descriptions. YAML is indented key-value pairs with 2 spaces per level.
+3. YAML not parsing? Compare with the remix sample in `learning-room/docs/samples/challenge-14-registration-remix-example.yml` and check indentation.
+4. Template does not appear in the chooser? Verify: filename ends in `.yml` or `.md`, you pushed the commit, and the file is in `.github/ISSUE_TEMPLATE/` folder.
+5. Testing in the template chooser is not working? Reload the Issues page, try a different repository, or ask facilitator for a test repository with write access.
+6. Remix approach feels overwhelming? Start by changing just the field labels and descriptions. Do not change the structure yet.
+7. Ask facilitator to review your template and suggest improvements.
+8. Finished but not sure you did it right? Compare your work against the [Challenge 14 reference solution](solutions/solution-14-template.md).
+
+> **Continue learning:** The GitHub Skills course [Introduction to Repository Management](https://github.com/skills/introduction-to-repository-management) covers templates and contributor settings in an interactive format. See [Appendix Z](appendix-z-github-skills.md) for the full catalog.
+
+### Learning Moment
+
+Templates are scaffolding. They do not restrict expert contributors - they guide newcomers. A template that takes 2 minutes to understand saves 30 minutes of back-and-forth questions later. By remixing a professional template, you learned how to make templates work for your specific context. That is how maintainers decide if a new template is worth creating: they adapt existing patterns first, then innovate.
+
+### Learning Pattern Used in This Chapter
+
+1. Analyze an existing, working example before building your own.
+2. Remix by changing content while keeping structure (safe, fast iteration).
+3. Create from scratch only after you understand the pattern (Markdown template).
+4. Test the result in the real environment (template chooser).
+
+
+## Table of Contents
+
+1. [What Is an Issue Template?](#1-what-is-an-issue-template)
+2. [How Templates Work on GitHub](#2-how-templates-work-on-github)
+3. [Navigating the Template Picker](#3-navigating-the-template-picker)
+4. [The Accessibility Agents Issue Templates](#4-the-accessibility-agents-issue-templates)
+5. [Creating a New Template - Step by Step](#5-creating-a-new-template---step-by-step)
+6. [YAML Form-Based Templates](#6-yaml-form-based-templates)
+7. [Building an Accessibility Bug Report Template](#7-building-an-accessibility-bug-report-template)
+8. [Pull Request Templates](#8-pull-request-templates)
+9. [Hands-On Activity](#9-hands-on-activity)
+
+
+## 1. What Is an Issue Template?
+
+An issue template is a pre-filled Markdown file that appears when someone activates "New Issue." Instead of an empty editor, the contributor sees:
+
+- Instructions explaining what information is needed
+- Section headers guiding them through the report
+- Checkboxes for conditions to verify
+- Placeholder text showing the expected format
+
+### Why they matter for accessibility projects
+
+Accessibility bugs require specific context that general bug templates often omit:
+
+- Which screen reader and version?
+- Which browser and version?
+- Which operating system?
+- Which WCAG success criterion is affected?
+- Does the issue affect all users or only those with specific assistive technology?
+
+Without this context, maintainers ask follow-up questions - which delays the fix and uses everyone's time. A good accessibility template captures it all on the first submission.
+
+
+## 2. How Templates Work on GitHub
+
+Templates live in a specific folder in your repository:
+
+### Description
+
+Templates live inside your-repo/.github/. The ISSUE_TEMPLATE/ subfolder contains: bug_report.md (Markdown template), feature_request.md (Markdown template), accessibility-bug.yml (YAML form template), and config.yml (template chooser configuration). The pull_request_template.md file sits directly in .github/, not inside ISSUE_TEMPLATE/.
+
+**Markdown templates (`.md`):** Traditional template format. Pre-fills a text editor with structured Markdown content. Contributors edit the template directly, replacing instructions and placeholder text with their own content.
+
+**YAML form templates (`.yml`):** Modern form-based templates. Creates a proper form interface with labeled fields, dropdowns, checkboxes, and validation. Contributors fill in fields rather than editing freeform Markdown. Better for accessibility because each field has an explicit label announced by screen readers.
+
+**`config.yml`:** Controls the template chooser page - what templates appear, what their descriptions say, whether an external link (like a discussion forum) appears as an option, and crucially, **whether contributors can bypass templates entirely with a blank issue**.
+
+For accessibility projects, `config.yml` is important: disabling the blank issue option means every report arrives with the structure your project needs. A screen reader bug report without reproduction steps and AT version information is almost impossible to triage - the form prevents that by making those fields required.
+
+### Example `config.yml`
+
+```yaml
+blank_issues_enabled: false
+contact_links:
+  - name: Community Discussion
+    url: https://github.com/community-access/accessibility-agents/discussions
+    about: For questions and general discussion - not bugs
+  - name: Security Vulnerability
+    url: https://github.com/community-access/accessibility-agents/security/advisories/new
+    about: Please use private reporting for security issues
+```
+
+With `blank_issues_enabled: false`, the "Open a blank issue" link disappears from the template chooser. Contributors must use one of your structured templates or one of the contact links. This is one of the most effective ways to improve the quality of incoming issues in any project you maintain.
+
+### Learning Cards: How Templates Work on GitHub
+
+
    
+Screen reader users
+
+- Templates live in `.github/ISSUE_TEMPLATE/` -- navigate there in the Explorer (`Ctrl+Shift+E`) to review existing templates before creating new ones
+- YAML form templates (`.yml`) are better for screen readers than Markdown templates because each field has an explicit label announced by your screen reader
+- The `config.yml` file in `ISSUE_TEMPLATE/` controls whether blank issues are allowed -- set `blank_issues_enabled: false` to require templates
+
+
    
+
+
    
+Low vision users
+
+- YAML form templates render as labeled form fields on GitHub.com, making them easier to fill out at high zoom than freeform Markdown editors
+- Template filenames use lowercase with hyphens (e.g., `accessibility-bug.yml`) -- look for them in the `.github/ISSUE_TEMPLATE/` folder in the Explorer
+- The template chooser page on GitHub shows each template's name and description in a card layout that scales well with browser zoom
+
+
    
+
+
    
+Sighted users
+
+- Look in `.github/ISSUE_TEMPLATE/` in the file tree -- `.md` files are Markdown templates, `.yml` files are YAML form templates, and `config.yml` configures the chooser
+- The `about:` field in each template's frontmatter becomes the description shown on the template chooser page
+- Template labels auto-apply when someone submits an issue using that template -- check the `labels:` array in the frontmatter
+
+
    
+
+
+## 3. Navigating the Template Picker
+
+When a repository has multiple templates, GitHub shows a template chooser page before the issue editor.
+
+
    
+Visual / mouse users
+
+1. Click the **Issues** tab on any repository
+2. Click the **New issue** button
+3. The template chooser page loads - templates appear as cards with a title, description, and "Get started" button
+4. Click **"Get started"** on the template you want
+5. The issue editor opens with that template's content pre-filled
+
+
    
+
+
    
+Screen reader users - NVDA / JAWS (Windows)
+
+1. Navigate to the Issues tab (press `T` from the repository tabs landmark)
+2. Activate "New issue" button
+3. The template chooser page loads
+4. Each template appears as a list item or a link
+5. Use `Tab` to move between templates
+6. Each template shows: name, description, "Get started" button
+7. Activate "Get started" on your chosen template
+
+
    
+
+
    
+Screen reader users - VoiceOver (macOS)
+
+1. Navigate to the Issues tab (`VO+Right` from the tab bar landmark)
+2. `VO+Space` to activate "New issue"
+3. The chooser page loads - templates appear as list items
+4. `VO+Right` to move between templates
+5. `VO+Space` on "Get started" for your chosen template
+
+
    
+
+**Note:** GitHub's improved Issues experience provides proper keyboard accessibility for the template chooser. This feature may already be active in your account.
+
+### Bypassing the Chooser
+
+If you want to file an issue without using a template:
+
+- Scroll past all templates to the bottom of the chooser page
+- Activate "Open a blank issue"
+
+### Learning Cards: Navigating the Template Picker
+
+
    
+Screen reader users
+
+- On the template chooser page, press `Tab` to cycle through template options -- each one announces its name and description
+- Press `Enter` on a template to select it and open the issue editor pre-filled with that template's content
+- If blank issues are disabled, the "Open a blank issue" link is absent -- all contributors must use a structured template
+
+
    
+
+
    
+Low vision users
+
+- The template chooser displays each option as a card with its name in bold and description below -- use browser zoom (`Ctrl+=`) to enlarge the cards
+- Contact links (for security issues or external trackers) appear alongside templates in the chooser with a distinct link icon
+- The "Get started" button next to each template is clearly visible and clickable at any zoom level
+
+
    
+
+
    
+Sighted users
+
+- The template chooser page shows cards for each template with a green "Get started" button -- click to begin
+- Contact links appear with a different icon (external link arrow) distinguishing them from standard issue templates
+- If configured, blank issues are disabled and only the structured template cards appear
+
+
    
+
+
+## 4. The Accessibility Agents Issue Templates
+
+Accessibility Agents uses templates to structure contributions. Navigate to `.github/ISSUE_TEMPLATE/` in the repository to read them.
+
+
    
+Visual / mouse users
+
+1. Click the **Code** tab on the repository
+2. Click the `.github` folder in the file listing
+3. Click `ISSUE_TEMPLATE`
+4. You'll see the template files - click any to read it
+
+
    
+
+
    
+Screen reader users (NVDA / JAWS / VoiceOver)
+
+1. Open the Code tab
+2. Use `Ctrl+Alt+Down/Up` (NVDA/JAWS) or `VO+Arrow` (VoiceOver) in the files table to reach the `.github` folder
+3. Activate the folder
+4. Activate `ISSUE_TEMPLATE`
+5. You will see the template files listed
+
+
    
+
+### Reading a Template File
+
+Open any template file (e.g., `bug_report.md`) in VS Code or in the GitHub web editor (pencil button - screen readers announce it as "Edit this file").
+
+Look for:
+
+- **Frontmatter** (between `---` delimiters): name, about, title, labels, assignees
+- **Body**: The template content with `##` headings, `` HTML comments as instructions, and placeholder text
+
+#### Example frontmatter
+
+```yaml
+name: Bug Report
+about: Report a problem with an agent or prompt
+title: '[BUG] '
+labels: bug
+assignees: ''
+```
+
+The `about` text appears in the template chooser. The `title` pre-fills the issue title field (the contributor replaces the placeholder). The `labels` array auto-applies labels when the issue is created.
+
+
+## 5. Creating a New Template - Step by Step
+
+### Tool Cards: Create an Issue Template
+
+**github.com (browser):**
+1. Go to **Settings > General** (scroll to Features section) > **Set up templates**.
+2. Choose a starter template or create a blank one.
+3. Edit the template content and click **Propose changes** to commit.
+
+**VS Code Desktop / github.dev:**
+1. Create the file `.github/ISSUE_TEMPLATE/your-template.md` (or `.yml` for form-based).
+2. Add YAML frontmatter (`name`, `description`, `title`, `labels`) and body content.
+3. Commit and push.
+
+**Git CLI / GitHub CLI:**
+```bash
+mkdir -p .github/ISSUE_TEMPLATE
+# Create and edit your template file, then:
+git add .github/ISSUE_TEMPLATE/
+git commit -m "feat: add issue template"
+git push
+```
+
+### Choosing Between Markdown and YAML Templates
+
+> **See also:** [Appendix Q: GitHub Actions](appendix-q-actions-workflows.md) covers how templates connect to automated workflows.
+
+Before creating a template, decide which format best suits your needs:
+
+| Factor | Markdown Templates | YAML Form Templates |
+| --------  | -------------------  | ---------------------  |
+| **Best for** | Simple templates, freeform text | Structured data collection, accessibility |
+| **Complexity** | Very simple to create | More complex, requires YAML knowledge |
+| **Screen reader UX** | Announces as pre-filled text editor | Announces each field with explicit labels |
+| **Validation** | None - contributors can delete anything | Can mark fields as required, validate input |
+| **Flexibility** | Full Markdown formatting freedom | Limited to defined field types |
+| **Data consistency** | Varies - contributors may skip sections | High - dropdowns ensure consistent values |
+| **Learning curve** | Minimal | Moderate |
+| **Maintenance** | Easy - just edit Markdown | More involved - must update YAML structure |
+
+#### Use Markdown templates when
+
+- You want contributors to have maximum flexibility in how they write
+- The template is primarily instructional text with minimal structured data
+- Your contributor base is comfortable with Markdown
+- You don't need validation or required fields
+
+#### Use YAML form templates when
+
+- You need specific, structured information (OS, browser, version numbers)
+- You want to guide less experienced contributors with dropdowns and validation
+- Screen reader accessibility is critical (labeled form fields are more accessible)
+- You want to ensure data consistency for automated triage or analysis
+- You need required fields that contributors cannot skip
+
+**For accessibility projects:** YAML form templates are strongly recommended. Accessibility bug reports require specific context (screen reader, browser, OS, version numbers) that Markdown templates rely on contributors to remember. Form templates make these fields explicit and required.
+
+
+### Markdown Template Structure
+
+A Markdown template consists of two parts:
+
+**1. YAML Frontmatter** (between `---` delimiters)
+
+Defines metadata about the template:
+
+```yaml
+name: Bug Report                    # Name shown in template chooser
+about: Report a bug or error        # Description in template chooser
+title: '[BUG] '                     # Pre-filled issue title (user can edit)
+labels: ['bug', 'needs-triage']     # Auto-applied labels
+assignees: ''                       # Auto-assigned maintainers (optional)
+```
+
+#### 2. Markdown Body
+
+The template content that pre-fills the issue editor:
+
+```markdown
+## Describe the Bug
+A clear and concise description of what the bug is.
+
+## Steps to Reproduce
+1. Go to '...'
+2. Click on '...'
+3. Scroll down to '...'
+4. See error
+
+## Expected Behavior
+What you expected to happen.
+
+## Actual Behavior
+What actually happened.
+
+## Environment
+- **OS:** [e.g. Windows 11, macOS Sonoma]
+- **Browser:** [e.g. Chrome 124, Firefox 125]
+- **Screen Reader:** [e.g. NVDA 2025.3.3, VoiceOver]
+
+## Additional Context
+Add any other context about the problem here.
+```
+
+### Markdown template tips
+
+- Use `##` headings to create clear sections
+- Use HTML comments `` for instructions that shouldn't appear in final issue
+- Use `**Bold text**` for field names to make them stand out
+- Use bullet lists or numbered lists for checklists
+- Be specific: "Browser version (e.g. Chrome 124)" is better than "Browser"
+- Include examples in brackets: `[e.g. ...]` helps contributors understand format
+
+
+### Complete Markdown Template Example
+
+Here's a complete accessibility bug report template in Markdown format. Save this as `.github/ISSUE_TEMPLATE/accessibility-bug-simple.md`:
+
+```markdown
+name: Accessibility Bug (Markdown)
+about: Report an accessibility issue using the simple Markdown template
+title: '[A11Y] '
+labels: ['accessibility', 'needs-triage']
+assignees: ''
+
+
+
+## Component Affected
+
+
+
+- [ ] @daily-briefing
+- [ ] @issue-tracker
+- [ ] @pr-review
+- [ ] @analytics
+- [ ] @insiders-a11y-tracker
+- [ ] Slash command (specify below)
+- [ ] Documentation
+- [ ] Setup or configuration
+- [ ] Other: ___________
+
+## Your Assistive Technology Setup
+
+**Screen Reader:** [e.g. NVDA 2025.3.3, JAWS 2026, VoiceOver macOS Sonoma]  
+**Browser:** [e.g. Chrome 124, Firefox 125, Safari 17]  
+**Operating System:** [e.g. Windows 11, macOS Sonoma 14.3, Ubuntu 22.04]  
+**Keyboard only (no screen reader):** [ ] Yes  [ ] No
+
+## Expected Behavior
+
+
+
+
+
+## Actual Behavior
+
+
+
+
+
+## Steps to Reproduce
+
+1. 
+2. 
+3. 
+4. Result: 
+
+## WCAG Success Criterion (if known)
+
+
+
+- [ ] 1.1.1 Non-text Content
+- [ ] 1.3.1 Info and Relationships
+- [ ] 2.1.1 Keyboard
+- [ ] 2.4.3 Focus Order
+- [ ] 2.4.6 Headings and Labels
+- [ ] 4.1.2 Name, Role, Value
+- [ ] Other: ___________
+- [ ] Not sure
+
+## Additional Context
+
+
+
+
+
+## Before Submitting
+
+- [ ] I searched for existing issues and this is not a duplicate
+- [ ] I can reliably reproduce this issue with the steps above
+- [ ] I have included my screen reader and browser versions
+```
+
+### When to use this Markdown version instead of YAML
+
+- Your contributors are comfortable with Markdown and prefer editing text
+- You want contributors to have more freedom in how they structure their report
+- The template is for an internal project where you know all contributors
+- You want a simpler template that's easier to modify later
+
+### Markdown template accessibility considerations
+
+- Checkboxes use `- [ ]` syntax (Markdown task lists)
+- Instructions are in HTML comments `` so they don't clutter the final issue
+- Bracket placeholders `[e.g. ...]` show expected format
+- Section headings use `##` for clear document structure
+- Screen readers can navigate by heading through the template
+
+
+### Creating Markdown Templates: The Manual Workflow (Browser)
+
+
    
+Visual / mouse users
+
+1. Navigate to your fork of [accessibility-agents](https://github.com/Community-Access/accessibility-agents) on GitHub
+2. Click the **Settings** tab
+3. Scroll to the "Features" section → click the checkmark next to "Issues" → click **"Set up templates"**
+4. Or navigate directly to `.github/ISSUE_TEMPLATE/` in your fork → click the `+` button → "Create new file"
+5. GitHub opens a template editor. Fill in the template name, about description, and body
+6. GitHub auto-populates the filename - you can change it
+7. Click **"Propose changes"** → create a PR to add the template
+
+
    
+
+
    
+Screen reader users (NVDA / JAWS / VoiceOver)
+
+1. Navigate to your fork of [accessibility-agents](https://github.com/Community-Access/accessibility-agents) on GitHub
+2. Go to the Settings tab (press `T` from the tabs landmark, then navigate to "Settings")
+3. Scroll to the "Features" section → find "Issues" → activate "Set up templates"
+
+   *Alternative:* Navigate directly to `.github/ISSUE_TEMPLATE/` → activate the "+" button → "Create new file"
+
+4. GitHub opens a template editor. Fill in:
+   - Template name: what appears in the chooser heading
+   - About: the description in the chooser
+   - Template content: the Markdown body
+5. GitHub auto-populates the filename based on your template name
+6. "Propose changes" → create a PR to add the template
+
+
    
+
+### Creating Markdown Templates: The VS Code Workflow
+
+1. Open your [accessibility-agents](https://github.com/Community-Access/accessibility-agents) fork in VS Code
+2. Navigate in Explorer to `.github/ISSUE_TEMPLATE/`
+3. Create a new file: `Ctrl+N` → save as `your-template-name.md` in that folder
+4. Add frontmatter first (between `---` delimiters), then the body
+5. Commit and push: open Source Control (`Ctrl+Shift+G`) → stage → commit → push
+
+#### File naming conventions
+
+- Use lowercase with hyphens: `accessibility-bug.md`, `feature-request.md`
+- Be descriptive: `security-vulnerability.md` is better than `security.md`
+- Avoid spaces in filenames
+
+### Learning Cards: Creating a New Template
+
+
    
+Screen reader users
+
+- Create template files in VS Code at `.github/ISSUE_TEMPLATE/your-template.yml` -- use `Ctrl+Shift+E` to navigate to the folder, then `Ctrl+N` to create a new file
+- YAML form templates use explicit `label:` fields that your screen reader announces for each form input -- prefer `.yml` over `.md` for accessibility
+- Test your template by pushing to GitHub and opening a new issue -- tab through every field with your screen reader to verify labels are announced
+
+
    
+
+
    
+Low vision users
+
+- YAML syntax uses indentation and colons -- enable "Render Whitespace" in VS Code Settings (`Ctrl+,` then search `renderWhitespace`) to see spaces clearly
+- Use a YAML linter extension to catch indentation errors before pushing -- errors show as red squiggles in the editor
+- Preview your Markdown template content by opening it in Markdown Preview (`Ctrl+Shift+V`) to verify formatting
+
+
    
+
+
    
+Sighted users
+
+- YAML form templates use a structured syntax: each field starts with `- type:` followed by `id:`, `attributes:`, and `validations:` properties
+- Use the VS Code Outline view (`Ctrl+Shift+O`) to navigate between YAML keys in large template files
+- Compare your template structure against existing templates in `.github/ISSUE_TEMPLATE/` to match the project's conventions
+
+
    
+
+
+## 6. YAML Form-Based Templates
+
+YAML templates create a proper form interface - labeled fields, dropdowns, checkboxes - rather than a pre-filled text editor. This is the preferred format for modern GitHub projects, especially those focused on accessibility.
+
+### Why YAML Forms Are Better for Accessibility
+
+**Explicit labels:** Each field has a `label:` that screen readers announce. In Markdown templates, users must infer structure from headings and placeholder text.
+
+**Structured navigation:** Screen readers can navigate form fields with standard form navigation commands (`F` key in NVDA/JAWS, form controls in VoiceOver rotor).
+
+**Required field validation:** Screen readers announce when a field is required before the user submits. Markdown templates have no validation.
+
+**Consistent data:** Dropdowns provide options that screen readers can navigate (`Up/Down Arrow` to hear each choice). contributors don't have to guess valid values.
+
+**Skip unreadable instructions:** HTML comments in Markdown templates (``) can confuse some screen reader configurations. YAML `markdown` fields provide instruction text that renders as readable content, not editing noise.
+
+
+### YAML Template Structure
+
+A YAML form template consists of several parts:
+
+```yaml
+name: Issue Template Name         # Shows in template chooser
+description: Longer description   # Shows in template chooser
+title: "[TAG] "                   # Pre-filled issue title
+labels: ["label1", "label2"]      # Auto-applied labels
+assignees: ["username"]           # Auto-assigned (optional)
+body:                             # Array of form fields
+  - type: markdown
+    attributes:
+      value: |
+        Instructional text here
+
+  - type: input
+    id: unique-field-id
+    attributes:
+      label: Field Label
+      description: Help text under the label
+      placeholder: Placeholder text in the field
+    validations:
+      required: true
+```
+
+#### Top-level keys
+
+- `name` (required): Template name in chooser
+- `description` (required): Template description in chooser
+- `title` (string): Pre-fills issue title, contributor can edit
+- `labels` (array): Labels auto-applied when issue is created
+- `assignees` (array): Usernames auto-assigned when issue is created
+- `body` (array): The form fields (required)
+
+
+```yaml
+name: Accessibility Bug Report
+description: Report an accessibility issue in Accessibility Agents' output or interface
+title: "[A11Y] "
+labels: ["accessibility", "needs-triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for reporting an accessibility issue.
+        Please fill in as much detail as possible.
+
+  - type: dropdown
+    id: screen-reader
+    attributes:
+      label: Screen Reader
+      description: Which screen reader are you using?
+      options:
+        - NVDA (Windows)
+        - JAWS (Windows)
+        - VoiceOver (macOS)
+        - VoiceOver (iOS)
+        - TalkBack (Android)
+        - Narrator (Windows)
+        - Orca (Linux)
+        - None
+    validations:
+      required: true
+
+  - type: checkboxes
+    id: checked-existing
+    attributes:
+      label: Before Submitting
+      options:
+        - label: I searched for existing issues and this is not a duplicate
+          required: true
+        - label: I am using the modern GitHub Issues experience (default since Jan 2026)
+          required: false
+```
+
+### YAML Field Types Reference
+
+GitHub supports several field types in YAML form templates. Each has specific attributes and uses:
+
+#### 1. `markdown` - Instructional Text
+
+Displays formatted Markdown content. Not editable by the contributor. Use for instructions, warnings, or explanations.
+
+```yaml
+- type: markdown
+  attributes:
+    value: |
+      ## Before You Begin
+
+      Please search for [existing issues](../issues) before submitting.
+      Use this format for multi-line text.
+```
+
+##### Attributes
+
+- `value` (required): Markdown content to display. Use `|` for multi-line text.
+
+**No validation options** (static content)
+
+**Screen reader note:** This content is announced as regular text. Screen reader users can read it with their reading commands before moving to the next field.
+
+
+#### 2. `input` - Single-line Text Field
+
+A single-line text input. Best for short answers like version numbers, URLs, or names.
+
+```yaml
+- type: input
+  id: version
+  attributes:
+    label: Version Number
+    description: Which version of the software are you using?
+    placeholder: e.g., v2.4.1
+  validations:
+    required: true
+```
+
+##### Attributes
+
+- `label` (required): Field label, announced by screen readers
+- `description` (optional): Help text below the label
+- `placeholder` (optional): Placeholder text inside the field
+
+##### Validations
+
+- `required` (boolean): Whether the field must be filled
+
+**Screen reader announcement:** "Version Number, required, edit text, Which version of the software are you using?"
+
+
+#### 3. `textarea` - Multi-line Text Area
+
+A multi-line text input. Best for descriptions, reproduction steps, code snippets, or any long-form content.
+
+```yaml
+- type: textarea
+  id: description
+  attributes:
+    label: Describe the Issue
+    description: Provide as much detail as possible
+    placeholder: |
+      When I navigate to...
+      The screen reader announces...
+      I expected...
+    value: |
+      This text pre-fills the textarea.
+      Contributors can edit or replace it.
+    render: markdown
+  validations:
+    required: true
+```
+
+##### Attributes
+
+- `label` (required): Field label
+- `description` (optional): Help text
+- `placeholder` (optional): Placeholder text (multi-line with `|`)
+- `value` (optional): Pre-filled content (multi-line with `|`)
+- `render` (optional): Syntax highlighting hint (e.g., `markdown`, `python`, `javascript`)
+
+##### Validations
+
+- `required` (boolean): Whether the field must be filled
+
+**Accessibility tip:** Use `placeholder` for examples, `value` for pre-filled template text that contributors should edit.
+
+
+#### 4. `dropdown` - Select Menu
+
+A dropdown menu with predefined options. Contributors select one choice. Best for bounded answer spaces like OS, browser, or severity.
+
+```yaml
+- type: dropdown
+  id: browser
+  attributes:
+    label: Browser
+    description: Which browser are you using?
+    options:
+      - Google Chrome
+      - Mozilla Firefox
+      - Microsoft Edge
+      - Apple Safari
+      - Other
+    multiple: false
+  validations:
+    required: true
+```
+
+##### Attributes
+
+- `label` (required):Field label
+- `description` (optional): Help text
+- `options` (required): Array of choices (strings)
+- `multiple` (boolean, default `false`): Whether user can select multiple options
+
+##### Validations
+
+- `required` (boolean): Whether a selection is required
+
+##### Screen reader experience
+
+1. Field is announced as "Browser, required, combo box"
+2. Press `Down Arrow` or `Alt+Down` to expand the dropdown
+3. `Up/Down Arrow` to navigate options
+4. Screen reader announces each option
+5. `Enter` or `Space` to select
+
+**Accessibility note:** Dropdowns are more accessible than free text for bounded choices. Screen reader users can hear all options and select precisely.
+
+
+#### 5. `checkboxes` - Checkbox Group
+
+A group of checkboxes. Contributors can select multiple options or use as a verification checklist.
+
+```yaml
+- type: checkboxes
+  id: prerequisites
+  attributes:
+    label: Before Submitting
+    description: Please verify these items
+    options:
+      - label: I searched for existing issues
+        required: true
+      - label: I can reproduce this issue reliably
+        required: true
+      - label: I have attached relevant logs or screenshots
+        required: false
+```
+
+##### Attributes
+
+- `label` (required): Group label
+- `description` (optional): Group description
+- `options` (required): Array of checkbox objects
+
+##### Each checkbox option
+
+- `label` (required): Checkbox label (what the user sees)
+- `required` (boolean, default `false`): Whether this checkbox must be checked
+
+**No top-level validation** - validation is per-checkbox in `options`
+
+##### Screen reader experience
+
+1. Group label announced: "Before Submitting, Please verify these items"
+2. Each checkbox announced as "I searched for existing issues, checkbox, not checked, required"
+3. Screen reader users can check each box with `Space`
+
+**Accessibility note:** Checkboxes with `required: true` prevent submission if unchecked. This enforces contribution guidelines (e.g., "search for duplicates first").
+
+
+### YAML Field Types Summary Table
+
+| Type | Best For | Key Attributes | Validations | Screen Reader Announced As |
+| ------  | ----------  | ----------------  | -------------  | ----------------------------  |
+| `markdown` | Instructions, warnings, explanations | `value` | None | Regular text content |
+| `input` | Version numbers, URLs, short text | `label`, `placeholder` | `required` | "Edit text" or "Edit" |
+| `textarea` | Descriptions, steps, code, long text | `label`, `placeholder`, `render` | `required` | "Multi-line edit" or "Text area" |
+| `dropdown` | OS, browser, severity, bounded choices | `label`, `options`, `multiple` | `required` | "Combo box" or "Pop-up button" |
+| `checkboxes` | Verification lists, multiple selections | `label`, `options` with per-item `required` | Per-checkbox | "Checkbox, not checked" |
+
+#### Choosing the right field type
+
+- If the answer is one of 2-10 known values → `dropdown`
+- If the answer is a short string (1-2 words) → `input`
+- If the answer is multiple sentences or a code block → `textarea`
+- If the contributor must verify multiple conditions → `checkboxes` with `required: true`
+- If you need to explain something → `markdown`
+
+### Learning Cards: YAML Form Templates
+
+
    
+Screen reader users
+
+- YAML form fields are announced by screen readers with their `label:` and `description:` values -- verify these are descriptive by tabbing through the rendered form on GitHub
+- Dropdown fields (`type: dropdown`) announce options as a listbox; use `Up/Down Arrow` to select and `Enter` to confirm
+- Required fields are announced with "required" before the label -- use `validations: required: true` in your YAML to enforce this
+
+
    
+
+
    
+Low vision users
+
+- YAML form templates render as proper HTML forms on GitHub with labeled inputs, dropdowns, and checkboxes that scale with browser zoom
+- Textarea fields expand as you type, so content remains visible without scrolling at high zoom
+- Error messages for required fields appear in red text below the field -- increase browser zoom if these are hard to read
+
+
    
+
+
    
+Sighted users
+
+- YAML forms render as polished HTML forms on GitHub with clear field labels, placeholder text, and validation indicators
+- Required fields show a red asterisk next to the label; optional fields have no indicator
+- Use the `markdown` field type to add explanatory text between form fields -- it renders as styled HTML in the form
+
+
    
+
+
+## 7. Building an Accessibility Bug Report Template
+
+This is the hands-on activity. You will create a YAML form template specifically for accessibility bug reports in [accessibility-agents](https://github.com/Community-Access/accessibility-agents).
+
+### Full Template
+
+Save this as `.github/ISSUE_TEMPLATE/accessibility-bug.yml` in your fork:
+
+```yaml
+name: Accessibility Bug Report
+description: Report an issue where Accessibility Agents output or behavior is not accessible to screen reader users or keyboard-only users
+title: "[A11Y] "
+labels: ["accessibility", "needs-triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        ## Thank You for This Report
+
+        Accessibility bug reports are some of the most important contributions
+        this project receives. The more detail you provide, the faster we can
+        reproduce and fix the issue.
+
+        **Before submitting:** Please check existing issues to avoid duplicates.
+        You can search: `is:open is:issue label:accessibility`
+
+  - type: dropdown
+    id: component
+    attributes:
+      label: Which Agent or Feature Is Affected?
+      options:
+        - "@daily-briefing"
+        - "@issue-tracker"
+        - "@pr-review"
+        - "@analytics"
+        - "@insiders-a11y-tracker"
+        - "A slash command (specify below)"
+        - "Documentation"
+        - "Setup or configuration"
+        - "Other"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: screen-reader
+    attributes:
+      label: Screen Reader
+      description: Which screen reader are you using? Select all that apply by filing separate issues, or list multiple in "Additional Context" below.
+      options:
+        - NVDA (Windows)
+        - JAWS (Windows)
+        - VoiceOver (macOS)
+        - VoiceOver (iOS / iPadOS)
+        - TalkBack (Android)
+        - Narrator (Windows)
+        - Orca (Linux)
+        - Keyboard only (no screen reader)
+        - None of the above
+    validations:
+      required: true
+
+  - type: input
+    id: screen-reader-version
+    attributes:
+      label: Screen Reader Version
+      description: For example, "NVDA 2025.3.3" or "JAWS 2026"
+      placeholder: e.g., NVDA 2025.3.3
+    validations:
+      required: false
+
+  - type: dropdown
+    id: browser
+    attributes:
+      label: Browser
+      options:
+        - Google Chrome
+        - Microsoft Edge
+        - Mozilla Firefox
+        - Apple Safari
+        - Other
+    validations:
+      required: true
+
+  - type: input
+    id: browser-version
+    attributes:
+      label: Browser Version
+      placeholder: e.g., Chrome 124.0.6367.82
+
+  - type: dropdown
+    id: os
+    attributes:
+      label: Operating System
+      options:
+        - Windows 11
+        - Windows 10
+        - macOS Sequoia
+        - macOS Sonoma
+        - macOS Ventura
+        - iOS / iPadOS
+        - Android
+        - Linux
+        - Other
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Behavior
+      description: What should happen? What should your screen reader announce?
+      placeholder: |
+        When I activate the "Get started" button, my screen reader should announce
+        "Issue template: Accessibility Bug Report, heading level 2" and move
+        focus to the first form field.
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual Behavior
+      description: What actually happens? What does your screen reader announce (or not announce)?
+      placeholder: |
+        When I activate the "Get started" button, focus moves but my screen reader
+        announces nothing. I have to navigate manually to find where I am.
+    validations:
+      required: true
+
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to Reproduce
+      description: Numbered steps to reproduce the issue
+      placeholder: |
+        1. Navigate to accessibility-agents on GitHub
+        2. Activate "New issue"
+        3. On the template chooser, Tab to "Accessibility Bug Report"
+        4. Activate "Get started"
+        5. Result: [what happens]
+    validations:
+      required: true
+
+  - type: dropdown
+    id: wcag
+    attributes:
+      label: WCAG Success Criterion (if known)
+      description: Which accessibility standard does this appear to violate?
+      options:
+        - "1.1.1 Non-text Content"
+        - "1.3.1 Info and Relationships"
+        - "1.3.2 Meaningful Sequence"
+        - "1.4.1 Use of Color"
+        - "1.4.3 Contrast (Minimum)"
+        - "2.1.1 Keyboard"
+        - "2.1.2 No Keyboard Trap"
+        - "2.4.1 Bypass Blocks"
+        - "2.4.3 Focus Order"
+        - "2.4.6 Headings and Labels"
+        - "2.4.7 Focus Visible"
+        - "3.3.1 Error Identification"
+        - "4.1.2 Name, Role, Value"
+        - "4.1.3 Status Messages"
+        - "Not sure"
+        - "Does not apply"
+    validations:
+      required: false
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional Context
+      description: Anything else - screenshots (with alt text), links to related issues, workarounds you found, or suggestions for a fix
+
+  - type: checkboxes
+    id: checklist
+    attributes:
+      label: Before Submitting
+      options:
+        - label: I searched existing issues and this is not a duplicate
+          required: true
+        - label: I can reliably reproduce this issue with the steps above
+          required: true
+        - label: I have included my screen reader and browser versions
+          required: false
+```
+
+### What Makes This Template Accessible
+
+This template is itself an accessibility contribution:
+
+- Every dropdown limits input to valid options, reducing errors for all users
+- The "Before Submitting" checklist uses explicit checkbox labels, not just text
+- The textarea placeholders model the format of a good answer, not just describe it
+- The WCAG dropdown educates as it collects data
+- The "Additional Context" field is optional - a contributor with limited time can still file a useful report without this field
+
+
+### A Second Template: Feature Request Form
+
+The bug report template above is specific to accessibility issues. Once you understand the pattern, you can create templates for any contribution type. Here is a Feature Request template you can add to your own projects - it follows the exact same YAML structure.
+
+Save as `.github/ISSUE_TEMPLATE/feature-request.yml`:
+
+```yaml
+name: Feature Request
+description: Suggest a new agent, slash command, or improvement to Accessibility Agents
+title: "[FEAT] "
+labels: ["enhancement", "needs-triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        ## Suggest a Feature
+
+        Feature requests are welcome. The more specific your suggestion,
+        the easier it is to design and implement.
+
+  - type: dropdown
+    id: feature-area
+    attributes:
+      label: Feature Area
+      description: Which part of Accessibility Agents does this relate to?
+      options:
+        - New agent
+        - New slash command
+        - Existing agent improvement
+        - Output format / accessibility
+        - Documentation
+        - Configuration / preferences
+        - Other
+    validations:
+      required: true
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem or Gap
+      description: What is the problem you are trying to solve? What can you not currently do?
+      placeholder: |
+        I often need to... but there is no way to...
+        I find that the current output of @daily-briefing does not...
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed Solution
+      description: How would you like this to work?
+      placeholder: |
+        A new slash command called /weekly-digest that...
+        The @pr-review agent should additionally announce...
+    validations:
+      required: true
+
+  - type: textarea
+    id: accessibility-impact
+    attributes:
+      label: Accessibility Considerations
+      description: How does this feature affect screen reader users or keyboard-only navigation?
+      placeholder: |
+        This would improve the experience because...
+        Screen reader users would benefit by...
+
+  - type: checkboxes
+    id: checklist
+    attributes:
+      label: Before Submitting
+      options:
+        - label: I searched existing issues and discussions - this has not been suggested before
+          required: true
+        - label: This feature would benefit contributors beyond my personal workflow
+          required: false
+```
+
+**Why this matters for your own projects:** Every open source project you create or maintain can have issue templates. A project with good templates gets better bug reports and feature requests - which means less back-and-forth and faster, more confident triage. The templates you create here are skills you carry to every repository you own.
+
+
+### Designing Templates for Your Own Projects
+
+When designing templates for a project you maintain, use these principles:
+
+**Ask for the minimum that makes the report actionable.** Every optional field you add is a reason for a contributor with limited time to stop and not finish. Required fields should be information you genuinely cannot triage without.
+
+**Use dropdowns over free text when the answer space is bounded.** "Which operating system?" should be a dropdown, not a text field. Bounded dropdowns reduce typos, inconsistent labeling, and fields left blank.
+
+**Write textarea placeholders as examples, not instructions.** A placeholder that says "e.g., When I navigate to the Issues tab using NVDA in Chrome on Windows 11..." teaches the contributor what a good answer looks like. A placeholder that says "Describe the issue here" does not.
+
+**Include a pre-submission checklist.** Even one checkbox - "I searched for existing issues" - reduces duplicate reports significantly. The checklist also reinforces community norms: the act of checking a box is more memorable than reading a line of text.
+
+**Test every template with your screen reader before committing.** Navigate through the form, tab through all fields, confirm every label is announced correctly, and verify that required-field errors are surfaced in a way a screen reader user will encounter before submitting.
+
+### Learning Cards: Building an Accessibility Bug Report Template
+
+**Screen reader users:**
+- YAML indentation is invisible to your ears but critical to the parser -- use VS Code's "Editor: Detect Indentation" setting and listen for the indentation level announcement (`Alt+Shift+I` in NVDA) to catch misaligned fields before committing
+- When editing YAML `body:` fields, each `- type:` block begins at the same indent level; use line-by-line arrow navigation and listen for consistent leading whitespace to verify structure
+- Test your finished template by filing a real issue with your screen reader -- tab through every field, confirm labels are announced, and verify that required-field validation errors are spoken before the form submits
+
+**Low-vision users:**
+- Turn on VS Code bracket and indentation colorization (`"editor.guides.indentation": true`) so the nested YAML structure of `body > attributes > validations` is visually distinct at each level
+- Use the Minimap or breadcrumb bar to track your position in a long YAML file -- accessibility bug report templates can easily exceed 100 lines, and losing your place is common at high zoom
+- Preview the rendered form on GitHub.com at your working zoom level to confirm that dropdown options, placeholders, and help text are all readable without horizontal scrolling
+
+**Sighted users:**
+- Install the YAML extension in VS Code for red-squiggle validation as you type -- a single wrong indent in YAML silently breaks the field and GitHub shows no error, just a missing field
+- After pushing your template, open the "New issue" template chooser in an incognito window to verify it appears correctly; caching can hide updates in your normal browser session
+- Compare your template side-by-side with the accessibility-agents `accessibility-bug-report.yml` to check that you have not missed critical fields like assistive technology setup or WCAG criterion
+
+
+## 8. Pull Request Templates
+
+A pull request template appears as the default body of every new PR in your repository.
+
+**File location:** `.github/pull_request_template.md` (singular - only one PR template per repo)
+
+### Reading the Accessibility Agents PR Template
+
+Open `.github/pull_request_template.md` in VS Code. You will see the standard sections the project expects:
+
+```markdown
+## Description
+
+
+## Type of Change
+- [ ] New agent
+- [ ] New slash command
+- [ ] Bug fix
+- [ ] Documentation improvement
+- [ ] Accessibility improvement
+- [ ] Other (describe below)
+
+## How to Test
+
+
+## Accessibility Considerations
+
+
+## Related Issues
+
+```
+
+**Using it when opening a PR:** The template auto-fills the PR description field. Tab through the sections with your screen reader and fill in each one. Delete placeholder comments (``) - they will not appear in the rendered PR but can confuse screen readers if left in.
+
+### Learning Cards: Pull Request Templates
+
+
    
+Screen reader users
+
+- The PR template auto-fills the description field when you create a new PR -- `Tab` through the sections and your screen reader announces each heading
+- Use `Ctrl+F` to find `` placeholders and replace them with your content; press `F3` to jump to the next placeholder
+- Delete HTML comments (``) after filling in sections -- they are invisible visually but screen readers still announce them
+
+
    
+
+
    
+Low vision users
+
+- The PR template appears as pre-filled Markdown in the description editor -- use Preview mode to verify your formatting looks correct
+- Checkbox items (`- [ ]`) render as interactive checkboxes in the previewed PR -- click to toggle each one
+- The template uses standard Markdown headings that scale with browser zoom for easy reading
+
+
    
+
+
    
+Sighted users
+
+- When creating a PR, the description field is pre-populated with the template's headings and placeholder comments
+- Replace each `` comment with your content -- the Preview tab shows how it will render
+- Checklist items appear as clickable checkboxes in the rendered PR so reviewers can track progress
+
+
    
+
+### Learning Cards: Hands-On Activity
+
+**Screen reader users:**
+- When filing an issue using a YAML form template, Tab moves between form fields and your screen reader announces each label -- listen for "required" on mandatory fields so you do not submit an incomplete form
+- After submitting your test issue, navigate to it and use heading navigation (`H` key in browse mode) to verify that your field responses rendered under the correct headings
+- When verifying your own created template, file a test issue yourself and read the entire rendered output with your screen reader before asking others to use it
+
+**Low-vision users:**
+- The GitHub template chooser displays template names and descriptions in a list -- at high zoom, the descriptions may wrap; look for the bold template name as your anchor point
+- After filing your test issue, switch to the rendered view and check that dropdown selections, text areas, and checkbox states are all visible and correctly formatted at your zoom level
+- When testing your custom template in Exercise B, open the form at both 100% and your preferred zoom to catch layout breaks that only appear at magnification
+
+**Sighted users:**
+- Use the template chooser's visual cards to compare your new template against existing ones -- consistent naming, description length, and label style make the chooser look professional
+- After creating your template, file a test issue and screenshot the rendered output; compare it against the original YAML to verify every field type (dropdown, textarea, checkboxes) rendered as intended
+- Try the "Preview" tab on GitHub.com while editing Markdown templates to catch formatting issues before committing; YAML form templates have no preview, so you must test by filing a real issue
+
+
+## 9. Hands-On Activity
+
+### Exercise A - Use an Existing Template
+
+**Your Mission:** File your first issue using a structured template. You'll experience the template as an end-user, which teaches you what good template design feels like.
+
+**What You'll Learn:** How templates guide contributors, what fields are required vs optional, and whether screen reader announced all fields clearly.
+
+
+#### Step 1: Navigate to the Accessibility Agents Issues Section
+
+##### What to do
+
+1. Open GitHub in your browser
+2. Navigate to the `community-access/accessibility-agents` repository (or your fork)
+3. Click the **Issues** tab (top navigation, between Pull Requests and Discussions)
+4. You should see a list of existing issues
+
+##### What you should see
+
+- A tab labeled "Issues" (currently active)
+- A list of open/closed issues below
+- A large green button labeled **"New issue"** on the right side
+
+1. Click the **"New issue"** button
+
+##### If you can't find it
+
+- Go directly to: `https://github.com/community-access/accessibility-agents/issues/new`
+- This opens the issue template chooser
+
+
+#### Step 2: View the Template Chooser with Your Screen Reader
+
+##### What to do
+
+1. You should now see a **Template Chooser** page
+2. The page displays available templates as buttons or links
+3. **With screen reader:** Navigate through the templates:
+   - NVDA/JAWS: Press `Tab` to move between templates, `Enter` to select one
+   - VoiceOver: Use `VO+Right Arrow` to move between elements, then `VO+Space` to activate
+4. Count the templates and read their descriptions aloud (or write them down):
+   - Template 1: [name] - [description]
+   - Template 2: [name] - [description]
+   - And so on...
+
+##### What you're listening for
+
+- Is each template name announced clearly?
+- Does the description explain what the template is for?
+- Is the UI structured so you don't accidentally skip a template?
+
+##### Write down
+
+- How many templates are available?
+- Which one seems closest to issues you identified on Day 1?
+
+
+#### Step 3: Select a Template
+
+##### What to do
+
+1. **Choose the template closest to a real issue type you identified on Day 1** (e.g., if you noted "screen reader navigation bug," select the Accessibility Bug Report template)
+2. Click it (or press `Enter` if focused with keyboard)
+
+##### What happens
+
+- The issue form opens
+- You see a form with labeled fields
+- Each field is pre-filled with helpful prompts or instructions
+
+##### If no template matches exactly
+
+- Choose **"Blank Issue"** or the most general template
+- You'll learn what an unstructured issue looks like (which teaches the *value* of templates)
+
+
+#### Step 4: Navigate the Form Fields
+
+##### What to do
+
+1. The issue form is now open
+2. Navigate through all visible fields using your screen reader or by tabbing:
+   - **NVDA/JAWS:** Press `Tab` to move to the next field, `Shift+Tab` to go back
+   - **VoiceOver:** Use `VO+Down Arrow` to read fields in order
+3. For each field, note:
+   - Field label (announced by screen reader)
+   - Help text or placeholder (hints about what to enter)
+   - Whether it's marked as required (usually with a red `*` or the word "required")
+4. **Write down at least 3 fields and whether each is required:**
+   - Field: [name] - Required? [Yes/No]
+
+
+#### Step 5: Fill In the Form
+
+##### What to do
+
+1. **Fill in at least 3 fields** with realistic content based on an issue you identified on Day 1
+   - Example: If the template asks "Screen Reader," select "NVDA"
+   - If it asks "Steps to reproduce," write 2-3 specific steps
+2. **For required fields marked with `*`:** Fill them in completely
+3. **For optional fields:** Choose at least one and fill it in (so you test optional fields)
+4. Don't worry about filling in *every* field - the point is to test the form
+
+##### What to expect
+
+- As you fill fields, you may see tooltips or error messages if you make a mistake
+- Some fields may change based on your selection (e.g., choosing a component shows related sub-options)
+
+
+#### Step 6: Preview the Issue Before Submitting
+
+##### What to do
+
+1. Look for a **Preview** tab or button (usually near the top of the form, next to "Write" or "Markdown")
+2. Click it (or press the hotkey shown)
+3. A preview pane appears showing how the issue will look when published
+
+##### With screen reader
+
+- NVDA/JAWS: Navigate to the preview area with `D` (region landmark)
+- VoiceOver: Use `VO+Right Arrow` to find the main content region
+- Read through the preview to confirm fields are formatted correctly
+
+##### What to look for
+
+- Are all the fields you filled in visible in the preview?
+- Are headings and section labels clear?
+- Would another person understand what you're reporting?
+- **If you use a screen reader:** Are all labels announced correctly in the preview?
+
+##### If something is unclear
+
+- Go back to the "Write" tab
+- Edit the fields
+- Preview again
+
+
+#### Step 7: Submit the Issue
+
+##### What to do
+
+1. Once you're satisfied with the preview, go back to the "Write" tab
+2. Locate the green **"New issue"** button (usually at the bottom of the form)
+3. **With keyboard:** Press `Tab` until the button is focused, then `Enter`
+4. **With mouse:** Click the button
+5. The issue is submitted and you see the new issue page with your content
+
+##### What happens
+
+- You see a confirmation: the issue is now live in the repository
+- The issue number appears (e.g., "#123")
+- Your issue is visible to all repository members
+
+
+#### Step 8: Checkpoint - Reflect on the Template
+
+After submitting, answer:
+
+1. **Template Clarity:** Did the template guide you toward providing useful information, or did fields feel confusing or unnecessary?
+2. **Screen Reader Accessibility:** Were all field labels announced clearly? Did you encounter any accessibility barriers?
+3. **Required vs Optional:** Was it obvious which fields were required? If you skipped an optional field, would you have known it was optional?
+4. **Context Helpfulness:** Did the placeholder text or help text under each field make you understand what information to provide?
+
+**Record these answers.** You'll use them in Exercise D when you design your own template.
+
+
+### Exercise B - Add the Accessibility Bug Report Template to Your Fork
+
+**Your Mission:** Create your own instance of the accessibility bug report template in your personal fork. This teaches you the file structure and gives you hands-on experience with YAML syntax.
+
+**What You'll Learn:** How templates are stored as files, what YAML syntax looks like, and how to test templates locally.
+
+**Prerequisites:**
+
+- You have already read Section 7 thoroughly (Building an Accessibility Bug Report Template)
+- You have a fork of [accessibility-agents](https://github.com/Community-Access/accessibility-agents) (created on Day 1)
+- VS Code is installed on your machine
+- Git is installed and configure with your GitHub credentials
+
+
+#### Step 1: Clone Your Fork to Your Machine
+
+##### What to do
+
+1. Open a terminal (PowerShell on Windows, Terminal on macOS/Linux)
+2. Navigate to a folder where you want to store the project:
+
+   ```bash
+   cd ~/projects
+   ```
+
+   (Or wherever you keep code projects)
+3. Clone your fork:
+
+   ```bash
+   git clone https://github.com/[YOUR-USERNAME]/accessibility-agents.git
+   ```
+
+   Replace `[YOUR-USERNAME]` with your actual GitHub username
+4. Wait for the clone to complete (should take 10-30 seconds)
+5. Navigate into the folder:
+
+   ```bash
+   cd accessibility-agents
+   ```
+
+##### What you should see
+
+- The terminal shows the folder structure being downloaded
+- Once complete, the prompt returns to `accessibility-agents $` or similar
+- You are now inside your local fork
+
+##### If you get an error
+
+- "Repository not found" → Make sure your GitHub username is correct
+- "Permission denied" → You may need to set up SSH keys (see [GitHub Docs: SSH Keys](https://docs.github.com/en/authentication/connecting-to-github-with-ssh))
+
+
+#### Step 2: Open Your Fork in VS Code
+
+##### What to do
+
+1. From the terminal, while in your [accessibility-agents](https://github.com/Community-Access/accessibility-agents) folder, type:
+
+   ```bash
+   code .
+   ```
+
+2. Press Enter
+3. VS Code opens with your fork loaded
+
+##### What you should see
+
+- VS Code opens a new window
+- The left sidebar shows the folder structure of [accessibility-agents](https://github.com/Community-Access/accessibility-agents)
+- At the top, you see the folder name: [accessibility-agents](https://github.com/Community-Access/accessibility-agents)
+
+##### If `code .` doesn't work
+
+- Use VS Code's File menu: **File** → **Open Folder** → navigate to your [accessibility-agents](https://github.com/Community-Access/accessibility-agents) folder
+
+
+#### Step 3: Navigate to the Templates Folder
+
+##### What to do
+
+1. In VS Code's file tree (left sidebar), expand the `.github` folder
+2. Inside, find and expand the `ISSUE_TEMPLATE` folder
+3. You should see existing template files (like `bug-report-template.yml` or similar)
+
+##### What you're looking at
+
+- Each `.yml` file is an issue template
+- These are the templates you saw in the GitHub UI when you filed an issue in Exercise A
+
+##### If the folder doesn't exist
+
+- Right-click on the `.github` folder and select **New Folder**
+- Name it `ISSUE_TEMPLATE`
+
+
+#### Step 4: Create a New Template File
+
+##### What to do
+
+1. Right-click on the `ISSUE_TEMPLATE` folder
+2. Select **New File**
+3. Name it: `accessibility-bug.yml` (exactly this name)
+4. Press Enter
+
+##### What happens
+
+- A new, empty file opens in the editor
+- The cursor is ready for you to start typing
+
+
+#### Step 5: Copy the Accessibility Template YAML
+
+##### What to do
+
+1. Go to [Chapter 17, Section 7](17-issue-templates.md#7-building-an-accessibility-bug-report-template) in this curriculum
+2. Find the complete YAML template code block (starting with `name:` and ending with the last field)
+3. **Select all the YAML code** (use `Ctrl+A` on the webpage or manually select)
+4. **Copy it** (`Ctrl+C`)
+5. Go back to VS Code
+6. **Paste it** into your new `accessibility-bug.yml` file (`Ctrl+V`)
+
+##### What you should see
+
+- The file now contains the full YAML template
+- Lines are numbered on the left
+- The syntax highlighting shows different colors for different parts (magenta for keys, blue for values)
+
+
+#### Step 6: Verify the YAML Syntax
+
+##### What to do
+
+1. Save the file (`Ctrl+S`)
+2. **Look at the bottom right of VS Code** - you may see some notifications
+3. Check if VS Code shows any red squiggly lines (indicating syntax errors)
+
+##### Common YAML errors to watch for
+
+- Missing colons after field names: `label:` should have a colon
+- Incorrect indentation (spaces, not tabs): Each nested line must be indented consistently
+- Unmatched quotes: If you have a `"` opening, there must be one closing it
+
+##### If you see red squiggles
+
+1. Hover over the error to see what VS Code suggests
+2. Compare your file with Section 7's template - look for extra/missing spaces or colons
+3. Make corrections and save again
+
+##### If you see no errors
+
+- Your YAML syntax is correct!
+
+
+#### Step 7: Create a Branch and Commit
+
+##### What to do
+
+1. Open the terminal in VS Code: **Terminal** → **New Terminal** (or `Ctrl+` ` on Windows)
+2. You should be in the [accessibility-agents](https://github.com/Community-Access/accessibility-agents) folder already
+3. Create a new branch for this change:
+
+   ```bash
+   git checkout -b feat/add-accessibility-template
+   ```
+
+4. Add the file to git:
+
+   ```bash
+   git add .github/ISSUE_TEMPLATE/accessibility-bug.yml
+   ```
+
+5. Commit with a message:
+
+   ```bash
+   git commit -m "feat: add accessibility bug report template"
+   ```
+
+6. Push to your fork:
+
+   ```bash
+   git push origin feat/add-accessibility-template
+   ```
+
+##### What happens
+
+- Git uploads your branch to GitHub
+- You're ready to test the template in the next step
+
+##### If you get errors
+
+- "Not a git repository" → Make sure you opened the [accessibility-agents](https://github.com/Community-Access/accessibility-agents) folder in VS Code
+- "Permission denied" → Make sure you authenticated with GitHub (see Prerequisites)
+
+
+#### Step 8: Test the Template in GitHub Web
+
+##### What to do
+
+1. Open GitHub in your browser
+2. Go to your fork: `https://github.com/[YOUR-USERNAME]/accessibility-agents`
+3. You should see a notification or purple bar saying **"Compare & pull request"** (your new branch)
+4. But instead of opening a PR, click the **Issues** tab
+5. Click **New issue**
+6. You should now see your new template in the chooser: **"Accessibility Bug Report"**
+7. Click it to open the form
+
+##### What you should see
+
+- The form displays your template fields in order
+- Each field has the label and description you defined
+- Dropdowns show the options you specified
+- Required fields are marked with a red `*`
+
+##### If you don't see the new template
+
+- Go back to the main repository page (code tab)
+- Refresh the browser (`Ctrl+Shift+R` for hard refresh)
+- Go back to Issues → New issue
+
+
+#### Step 9: Test with Your Screen Reader
+
+##### What to do
+
+1. **With screen reader activated:** Navigate through the template form using your reader's commands
+2. For each field, note:
+   - Is the label announced clearly?
+   - Is it obvious whether the field is required?
+   - Do dropdowns announce their options correctly?
+   - Are descriptions/help text announced?
+3. Answer:
+   - Did you encounter any accessibility barriers?
+   - Would a screen reader user find this template easy to use?
+
+**Record your findings** - you'll use this for Exercise D.
+
+
+#### Step 10: Merge Your Branch (Optional)
+
+##### What to do
+
+1. Open an PR for your branch:
+   - Go to your fork on GitHub
+   - You should see a **"Compare & pull request"** button
+   - Click it
+2. Add a title: `feat: add accessibility bug report template`
+3. Add a description: `This template guides contributors to report accessibility issues with clear fields for screen reader type, browser, and WCAG criteria.`
+4. Click **Create pull request**
+5. Review your PR (using skills from Chapter 14!)
+6. If satisfied, click **Merge pull request** to merge it into your fork's `main` branch
+
+##### Why merge?
+
+- It shows the template is finalized and tested
+- If you continue working on this fork, the template is ready for everyone who clones it
+
+
+#### Checkpoint
+
+After completing Steps 1-9, verify:
+
+1. You created a file named `accessibility-bug.yml` in `.github/ISSUE_TEMPLATE/`
+2. The file contains valid YAML (no red squiggles in VS Code)
+3. The template is visible when you click "New issue"  in your fork
+4. You tested it with your screen reader and noted any issues
+
+You're ready for Exercise C!
+
+### Exercise C - Submit It Upstream
+
+**Your Mission:** Contribute your tested template to the upstream `community-access/accessibility-agents` repository. This is a real open source contribution!
+
+**What You'll Learn:** The PR process for submitting contributions upstream, working with maintainers, and seeing your code merged into an open source project.
+
+**Prerequisites:**
+
+- You have completed Exercises A & B
+- You have created and tested the `accessibility-bug.yml` template in your fork
+- The template works without errors in your fork's issue template chooser
+
+
+#### Step 1: Verify Your Template is Ready
+
+Before submitting upstream, make sure your template is production-ready:
+
+##### What to do
+
+1. Go to your fork on GitHub
+2. Click **Issues** → **New issue**
+3. Verify your template appears and is named "Accessibility Bug Report"
+4. Open it and fill it out once more to confirm:
+   - All fields display correctly
+   - No broken formatting
+   - Dropdowns work properly
+   - Required fields are marked
+5. Don't submit this test issue - just close the tab
+
+##### What success looks like
+
+- The template is clean, no error messages
+- Every field is functional
+- You feel confident showing it to maintainers
+
+
+#### Step 2: Create the Pull Request
+
+##### What to do
+
+1. Stay on your fork's GitHub page
+2. You should see a **"Compare & pull request"** button (or look for your feature branch)
+3. If that button doesn't appear:
+   - Click the **Code** tab
+   - Click the **branches** dropdown
+   - Select your branch (`feat/add-accessibility-template`)
+   - Click **"New pull request"** to the right
+4. A PR creation page opens showing:
+   - **Base:** `community-access/accessibility-agents` / `main` (the upstream repo)
+   - **Head:** `[your-username]/accessibility-agents` / `feat/add-accessibility-template` (your fork/branch)
+5. Confirm this is correct - you're sending your branch to the upstream repository
+
+##### What you should see
+
+- A comparison showing your new file: `.github/ISSUE_TEMPLATE/accessibility-bug.yml`
+- One file changed, lines added, no lines removed
+- Below: an input form for PR title and description
+
+
+#### Step 3: Write Your PR Title and Description
+
+##### Form fields to fill
+
+##### Title
+
+```text
+feat: add accessibility bug report template
+```
+
+##### Description
+
+Write a clear description that explains what you're contributing:
+
+```text
+## What Does This PR Do?
+
+This PR adds a comprehensive GitHub issue template for filing accessibility 
+(a11y) bug reports. The template uses a form-based structure (YAML) to guide 
+contributors through providing crucial accessibility context.
+
+## Why Is This Useful?
+
+Accessibility issues are often under-reported because contributors don't know 
+what information maintainers need. This template standardizes that data:
+- Screen reader type (NVDA, JAWS, VoiceOver, etc.)
+- Browser and OS version
+- WCAG success criterion affected
+- Steps to reproduce the issue
+- Expected vs. actual behavior
+
+## How Was This Tested?
+
+- YAML syntax validated (no errors)
+- Template displays correctly in GitHub web UI
+- All fields announced clearly with screen reader (NVDA/JAWS/VoiceOver)
+- Dropdown options are navigable
+- Required fields are properly marked
+- Form preview is accessible
+
+## Related Issue
+
+Closes #[issue number] (if there is an open issue requesting this feature)
+```
+
+### What to do
+
+1. Copy the template above into the description field
+2. **Edit it** with your actual testing experience:
+   - Which screen reader(s) did you test with?
+   - Did you find any issues? (Be honest if you did!)
+   - Did you test with a colleague or friend for feedback?
+3. Keep it concise but thorough
+
+
+#### Step 4: Review Your PR Before Submitting
+
+##### What to do
+
+1. **Scroll down** and preview your PR description as it will appear
+2. Using your screen reader, read through it:
+   - Is the title clear about what you're adding?
+   - Does the description explain the value of this template?
+   - Are all checkmarks (``) and formatting visible?
+3. Make any corrections needed
+4. Do not submit yet - continue to Step 5
+
+
+#### Step 5: Submit the PR
+
+##### What to do
+
+1. Click the green **"Create pull request"** button
+2. Your PR is now submitted to the upstream repository
+3. You see a confirmation page showing your new PR number (e.g., "#42")
+4. GitHub may automatically assign reviewers or run CI checks
+
+##### What happens next
+
+- Repository maintainers will review your PR
+- They may leave comments asking for changes
+- You can push additional commits to your branch to address feedback
+- Once approved, a maintainer will merge your template into `community-access/accessibility-agents`
+
+##### What success looks like
+
+- Your PR appears in the upstream repository's PR list
+- You see comments from maintainers (positive feedback = great sign!)
+- Your contribution is now visible to everyone in the project
+
+
+#### Step 6: Respond to Feedback
+
+##### If maintainers leave comments
+
+##### What to do
+
+1. Read their feedback carefully using your screen reader
+2. Understand what changes they're requesting (or what they're praising!)
+3. **If changes are needed:**
+   - Go back to your fork in VS Code
+   - Edit the `accessibility-bug.yml` file accordingly
+   - Commit and push:
+
+     ```bash
+     git add .github/ISSUE_TEMPLATE/accessibility-bug.yml
+     git commit -m "Address feedback from maintainers: [brief description]"
+     git push origin feat/add-accessibility-template
+     ```
+
+   - Your changes automatically appear in the PR (linked to the branch)
+4. **Leave a reply comment** on the PR:
+
+   ```text
+   Thanks for the feedback! I've made the changes you requested 
+   in commit [commit hash]. The template now includes [what you changed].
+   ```
+
+5. Click **Reply**
+
+##### If no feedback after 48 hours
+
+- You can leave a polite comment: "Friendly ping - is there anything else needed from my end?"
+
+
+#### Step 7: Celebrate Your Contribution
+
+##### When your PR is merged
+
+1. You'll see the PR status change to "Merged"
+2. Your template is now part of the `community-access/accessibility-agents` repository
+3. Everyone who forks that repo will get your template
+4. You can claim this as a real open source contribution
+
+##### What to do
+
+- Take a screenshot of your merged PR
+-Write down: "I contributed [template name] to an open source project"
+- This is valuable experience for your resume and for learning how open source collaboration works
+
+
+#### Checkpoint
+
+After completing Steps 1-7, verify:
+
+1. You created a PR to the upstream repository
+2. Your PR includes a clear description of what you're contributing
+3. Your template is the only change in the PR (one file)
+4. You addressed any feedback from maintainers
+5. Your PR was merged (or is waiting for merge)
+
+##### Reflect
+
+- How did it feel to contribute to an upstream repository?
+- What did the maintainers' feedback teach you about accessibility templates?
+- Would you do this again for other projects?
+
+### Exercise D - Design a Template for Your Own Project
+
+**Your Mission:** Apply everything you've learned to design a template for a repository you own, maintain, or plan to create.
+
+**What You'll Learn:** How to make design decisions about required vs. optional fields, field types, and how to test your template with real users.
+
+**Time estimate:** 30-45 minutes (can be done after the workshop)
+
+
+#### Part 1: Choose Your Project
+
+##### What to do
+
+1. Think of a repository you have a personal connection to:
+   - A project you own or maintain
+   - A project you contribute to regularly
+   - A project you plan to create (even if just in your head)
+   - A project that's important to your workplace
+2. **Write down the project name** and briefly why chose it:
+
+   ```text
+   Project: [name]
+   Why it matters to me: [1 sentence]
+
+   Current state: Exists, I maintain it
+                  Exists, I contribute to it
+                  I'm planning to create it
+                  Other: [describe]
+   ```
+
+##### What success looks like
+
+- You have a specific project in mind (not generic)
+- You can articulate why you care about it
+
+
+#### Part 2: Identify Issue Patterns
+
+**Your task:** Study the issues your project receives (or would receive) to understand what information is most valuable.
+
+##### What to do
+
+##### If your project already has issues
+
+1. Open your issue list in GitHub
+2. **Read the last 5-10 issues** (or all open issues if fewer)
+3. For each issue, ask yourself:
+   - What problem was the reporter describing?
+   - What information helped you (or would help) understand the issue?
+   - What information was *missing* that you had to ask for?
+4. **Write down 3-5 patterns:**
+
+   ```text
+   Issue Type 1: [what kind of issues are most common?]
+   - Essential info needed: [what always helps?]
+   - Often missing: [what do you always have to ask for?]
+
+   Issue Type 2: [second most common type]
+   - Essential info needed: [what?]
+   - Often missing: [what?]
+   ```
+
+##### If your project doesn't exist yet or has no issues
+
+1. Think about the *type* of issues you'd want to receive:
+   - Bug reports?
+   - Feature requests?
+   - Documentation improvements?
+   - All of the above?
+2. For each type, ask: "If someone reported this issue, what would I need to know?"
+3. Write down:
+
+   ```text
+   Issue Type 1: [e.g., "Bug Report"]
+   - Essential info needed: [e.g., "What OS? Browser? Steps to reproduce?"]
+   - Questions I'd ask: [What follow-ups would I need?]
+
+   Issue Type 2: [e.g., "Feature Request"]
+   - Essential info needed: [e.g., "What problem does this solve?"]
+   - Questions I'd ask: [e.g., "Who else has asked for this?"]
+   ```
+
+##### What success looks like
+
+- You've identified at least 2-3 issue types
+- For each type, you know what information is crucial vs. nice-to-have
+
+
+#### Part 3: Design Your Required Fields
+
+**Your task:** List the fields you absolutely need to understand an issue.
+
+##### What to do
+
+**Rule:** Keep required fields minimal. If a field is required, you genuinely cannot triage without it.
+
+1. Create a table:
+
+   ```
+   Field Name -- Type (dropdown/input/textarea) -- Why Required? -- Options (if dropdown)
+   [name]     -- [type]                        -- [reason]      -- [choices]
+   ```
+
+2. For each issue type from Part 2, add 2-4 required fields:
+
+   **Example for "Bug Report":**
+
+   | Field | Type | Why? | Options |
+   | -------  | ------  | ------  | ---------  |
+   | Component | dropdown | "I have 5 components; knowing which is affected saves triage time" | Component A, B, C, D, E |
+   | Steps to Reproduce | textarea | "I cannot fix what I cannot replicate" | (free text) |
+   | OS | dropdown | "Bugs are often OS-specific" | Windows, macOS, Linux |
+
+3. **Write down at least 2 required fields:**
+
+   ```text
+   Required Field 1: [name]
+   - Type: [dropdown / input / textarea?]
+   - Why is it required? [explain as if to the issue reporter]
+   - If dropdown, options: [list them]
+
+   Required Field 2: [name]
+   - Type: [type]
+   - Why is it required? [explain]
+   - If dropdown, options: [list them]
+   ```
+
+##### What success looks like
+
+- You have 2-4 required fields
+- Each has a clear reason (not arbitrary)
+- You can explain to someone why each field is required
+
+
+#### Part 4: Design Your Optional Fields
+
+**Your task:** Add optional fields that would be helpful but aren't blocking.
+
+##### What to do
+
+1. **Brainstorm nice-to-have information:**
+   - Information that's helpful but you could triage without it
+   - Information that helps you prioritize or assign the issue
+   - Information that provides missing context
+
+2. **Example optional fields for a bug report:**
+   - Environment details (CPU, RAM, versions of dependencies)
+   - Screenshots or links
+   - Workarounds the reporter has found
+   - When the issue started happening
+
+3. **Write down at least 2 optional fields:**
+
+   ```text
+   Optional Field 1: [name]
+   - Type: [dropdown / input / textarea / checkboxes?]
+   - Why include it? [what does it help with?]
+
+   Optional Field 2: [name]
+   - Type: [type]
+   - Why include it? [what insight does it provide?]
+   ```
+
+4. **For each field, decide:**
+   - Should this be a dropdown (bounded choices) or free text (open-ended)?
+   - If dropdown, list the options
+   - If textarea, what's a helpful placeholder or example?
+
+##### What success looks like
+
+- You have 2-3 optional fields in addition to required ones
+- Each optional field would genuinely help, but you could still triage without it
+- Your template is neither overwhelming nor too sparse (aim for 5-7 fields total)
+
+
+#### Part 5: Write Field Placeholders and Help Text
+
+**Your task:** For each field, write helpful placeholder or description text that guides the reporter.
+
+##### What to do
+
+For each required and optional field, draft:
+
+1. **Field label** (the visible name)
+2. **Description** (short help text)
+3. **Placeholder** (example of what to type, for input/textarea fields)
+
+##### Examples
+
+```text
+Field: "Steps to Reproduce"
+Description: "Numbered list of actions that trigger the bug"
+Placeholder: "1. Open the settings menu
+2. Click 'Advanced Options'
+3. Toggle the switch
+4. The app crashes"
+
+
+Field: "Expected Behavior"
+Description: "What should happen if everything worked correctly?"
+Placeholder: "The settings should save silently and the app should remain open"
+```
+
+##### Write these for at least 3 of your fields
+
+```text
+Field 1: [name]
+Description: [guidance for the reporter]
+Placeholder: [example of good input]
+
+Field 2: [name]
+Description: [guidance]
+Placeholder: [example]
+
+Field 3: [name]
+Description: [guidance]
+Placeholder: [example]
+```
+
+##### What success looks like
+
+- Placeholder text shows a real example, not just "e.g., enter text here"
+- Description explains *why* you're asking, not just *what*
+- An inexperienced reporter could read these and understand what you need
+
+
+#### Part 6: Test Your Template Locally
+
+**Your task:** Create a draft YAML template file and test it with your screen reader.
+
+##### What to do
+
+1. **Create a text file** with your template in YAML format. Use Section 6 as a template:
+   - Start with the frontmatter (`name:`, `description:`, `title:`, `labels:`)
+   - Add your fields in the `body:` section
+   - Use appropriate field types (input, textarea, dropdown, checkboxes)
+
+2. **Save it locally** (not yet in GitHub):
+   - Name it: `[your-project-name]-template.yml`
+   - Save it to your desktop or a projects folder
+
+3. **Open it in VS Code** and check:
+   - Is the YAML syntax correct? (no red squiggles)
+   - Does every field have an `id`, `label`, and `attributes`?
+   - Are required fields in a `validations:` block?
+
+4. **Test the structure:**
+   - Print it out or read it aloud
+   - Does your field order make sense? (Related fields together?)
+   - Are required fields grouped before optional?
+   - Is any field confusing or unclear?
+
+5. **With your screen reader:**
+   - Open the YAML file in your editor
+   - Navigate through it with your reader
+   - Can you understand the structure: name, description, then body with fields?
+   - Are the field labels clear?
+
+##### If you find issues
+
+- Reorder fields for clarity
+- Simplify confusing help text
+- Remove fields that seem redundant
+- Save your changes
+
+##### What success looks like
+
+- Your YAML file has no syntax errors
+- You can read through it and understand the template flow
+- A screen reader user could navigate through the structure
+
+
+#### Part 7: (Optional) Deploy to GitHub and Test with a Friend
+
+**Your task:** Upload your template to a GitHub repository and test it with a colleague or friend.
+
+##### What to do
+
+This is optional but powerful - real user testing is the best validation.
+
+1. **Upload your template** to a test repository:
+   - Create a test branch in a personal repo
+   - Add your template file to `.github/ISSUE_TEMPLATE/`
+   - Push the branch
+
+2. **Ask a colleague or friend:**
+   - "Could you try filing an issue using this template?"
+   - "What did you find confusing?"
+   - "Did any required fields feel unnecessary?"
+   - "Were the descriptions helpful?"
+
+3. **Collect feedback:**
+   - What worked well?
+   - What was confusing?
+   - Did they skip any optional fields? (If yes, consider removing them)
+   - Would they suggest different field options?
+
+4. **Refine your template** based on their feedback
+
+
+#### Part 8: Reflect on Your Template Design
+
+**Your task:** Document what you learned from this exercise.
+
+##### What to do
+
+Write answers to these questions:
+
+1. **Decision-making:** Which field did you debate including? Why did you finally decide yes or no?
+
+   ```text
+   Field: [name]
+   Debate: [why was this hard to decide?]
+   Decision: [required / optional / removed]
+   Reason: [what made you decide?]
+   ```
+
+2. **Trade-offs:** You can't ask for everything without overwhelming reporters. What information did you choose *not* to ask for? Why?
+
+   ```text
+   Information I didn't include: [example]
+   Why I chose not to ask: [explanation]
+   Would I change this? [yes/no] + why
+   ```
+
+3. **Iteration:** If you had user feedback (from Part 7), what did you learn?
+
+   ```text
+   Feedback: [what did your friend/colleague say?]
+   Change you made: [how did you refine?]
+   Why it helped: [what improved?]
+   ```
+
+4. **Real-world readiness:** Would you actually deploy this template to a real project?
+
+   ```text
+   Readiness: Yes, I'm confident
+              Maybe, with more testing
+              No, I need to rethink some fields
+   Next step: [what would you do next?]
+   ```
+
+##### What success looks like
+
+- You can articulate why you made each design decision
+- You understand the trade-offs between comprehensive and overwhelming
+- You recognize where you'd improve with more user feedback
+
+
+#### Checkpoint
+
+After completing Parts 1-8, you have:
+
+- Chosen a specific project to design for
+- Identified issue patterns and common questions
+- Designed required fields (minimal, crucial information)
+- Designed optional fields (helpful but not blocking)
+- Written clear placeholder and description text
+- Tested your template locally for syntax and accessibility
+- (Optional) Got real user feedback and refined based on it
+- Reflected on your design decisions
+
+##### You now understand the thinking that separates "a blank text box" from "structured, actionable contributions."
+
+This skill - understanding what information *actually* matters - is what makes great templates. The YAML syntax is just the delivery mechanism. The hard part is the thinking you did in Parts 1-5.
+
+
+### You've Completed the Template Exercises
+
+You now:
+
+1. Understand templates from the user perspective (Exercise A)
+2. Can create and deploy templates yourself (Exercise B)
+3. Know how to contribute upstream (Exercise C)
+4. Can design templates with real thinking behind them (Exercise D)
+
+In **Chapter 16 (Accessibility Agents)**, you'll see how the `@template-builder` agent automates the YAML writing part - but *you* bring the design thinking from this exercise. The agent generates YAML; you decide what questions to ask.
+
+
+## 10. Day 2 Amplifier: The Template Builder Agent
+
+Everything you just learned - field types, YAML structure, accessibility testing - is core GitHub knowledge. Now see how Accessibility Agents amplifies it.
+
+Our 6th agent, **@template-builder**, is an interactive wizard that generates issue templates guided by your answers to simple questions. Instead of writing YAML by hand, you answer prompts and the agent produces a production-ready template in seconds.
+
+### How It Works
+
+#### In VS Code
+
+```text
+You: @template-builder create accessibility template
+Agent: [Ask Questions interface]
+  • Template name? → "Accessibility Bug Report"
+  • What's this for? → "Report screen reader and keyboard issues"
+  • First field? → "Screen Reader (dropdown)"
+  • Options? → "NVDA, JAWS, VoiceOver, TalkBack, Other"
+  • Required? → "Yes"
+  [... continues field by field]
+Agent: Here's your YAML template [syntax-highlighted code block]
+```
+
+Then you copy, paste to `.github/ISSUE_TEMPLATE/your-template.yml`, commit, and done.
+
+### Why It Matters
+
+| Approach | Time | Expertise | Error Rate |
+| ----------  | ------  | -----------  | -----------  |
+| Manual YAML | 15-20 min | High (YAML syntax) | Medium (typos, missing colons) |
+| Copy-Paste Example | 10-15 min | Medium | Low (if example is good) |
+| Agent-Guided | 2-3 min | Low (just describe) | Very Low (structured output) |
+
+The Template Builder does not teach you to design templates - Section 5 taught you that. It automates the mechanical part: translating your decisions into working YAML.
+
+### Using the Template Builder
+
+---
+
+*Next: [Chapter 18: Fork and Contribute](18-fork-and-contribute.md)*  
+*Back: [Chapter 16: GitHub Copilot](16-github-copilot.md)*  
+*Related appendices: [Appendix Q: GitHub Actions](appendix-q-actions-workflows.md) | [Appendix C: Markdown Reference](appendix-c-markdown-reference.md)*
+
diff --git a/admin/qa-bundle/docs/18-fork-and-contribute.md b/admin/qa-bundle/docs/18-fork-and-contribute.md
new file mode 100644
index 0000000..8bcfbd9
--- /dev/null
+++ b/admin/qa-bundle/docs/18-fork-and-contribute.md
@@ -0,0 +1,606 @@
+# Fork and Contribute: The Open Source Workflow
+
+> **Related appendices:** [Appendix E: Advanced Git](appendix-e-advanced-git.md) | [Appendix O: Branch Protection](appendix-o-branch-protection.md) | [Appendix D: Git Authentication](appendix-d-git-authentication.md)
+> **Authoritative sources:** [GitHub Docs: Fork a repo](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo) | [GitHub Docs: Syncing a fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork) | [Open Source Guides: How to Contribute](https://opensource.guide/how-to-contribute/)
+
+
+> **Day 2, Block 3 Material**
+>
+> This chapter teaches the complete fork-based contribution workflow from start to finish. You will fork a real repository, create a feature branch, make changes, push to your fork, and open a pull request against the upstream repository. This is the workflow used by millions of open source contributors every day, and it is the foundation for the capstone project in [Chapter 20](20-build-your-agent.md).
+
+## Table of Contents
+
+1. [What Is a Fork?](#1-what-is-a-fork)
+2. [Fork vs Clone vs Branch](#2-fork-vs-clone-vs-branch)
+3. [Step 1: Fork the Repository](#3-step-1-fork-the-repository)
+4. [Step 2: Clone Your Fork Locally](#4-step-2-clone-your-fork-locally)
+5. [Step 3: Add the Upstream Remote](#5-step-3-add-the-upstream-remote)
+6. [Step 4: Create a Feature Branch](#6-step-4-create-a-feature-branch)
+7. [Step 5: Make Your Changes](#7-step-5-make-your-changes)
+8. [Step 6: Push to Your Fork](#8-step-6-push-to-your-fork)
+9. [Step 7: Open a Pull Request](#9-step-7-open-a-pull-request)
+10. [Step 8: Respond to Review Feedback](#10-step-8-respond-to-review-feedback)
+11. [Keeping Your Fork in Sync](#11-keeping-your-fork-in-sync)
+12. [The Fork Workflow Checklist](#12-the-fork-workflow-checklist)
+13. [If You Get Stuck](#13-if-you-get-stuck)
+
+---
+
+> **Challenge 16: Build Your Agent (Capstone)** uses this fork-based workflow end to end. Practice it here so the capstone feels familiar.
+
+## 1. What Is a Fork?
+
+> **See also:** [Chapter 08: Open Source Culture](08-open-source-culture.md) for the cultural context of forking and contributing.
+
+A fork is your personal copy of someone else's repository on GitHub. When you fork a repository, GitHub creates a full copy under your account. You own the fork -- you can push to it, create branches on it, and modify it freely without affecting the original.
+
+The original repository is called the **upstream** repository. Your fork is linked to the upstream, which means you can open pull requests from your fork back to the original.
+
+### Why forks exist
+
+Forks solve a permissions problem. Most open source projects do not give every contributor write access to the main repository. Instead:
+
+1. You fork the project (creates your copy)
+2. You make changes on your copy
+3. You open a pull request asking the maintainers to merge your changes
+
+This way anyone can contribute without the maintainers giving out write access.
+
+> **The Day 1 connection:** On Day 1, you worked in the learning-room repository where you had write access. You created branches directly on the repository. In the open source world, you usually do not have write access to the upstream repository, so you fork first and branch on your fork.
+
+---
+
+## 2. Fork vs Clone vs Branch
+
+These three concepts are related but different. Understanding the distinctions prevents confusion.
+
+| Concept | Where it lives | What it creates | When to use it |
+|---|---|---|---|
+| **Fork** | GitHub.com (your account) | A copy of the entire repository under your GitHub account | When you want to contribute to a repo you do not own |
+| **Clone** | Your computer | A local copy of any repository (yours or someone else's) | When you want to work locally |
+| **Branch** | Inside any repository (local or remote) | A named pointer to a specific commit | When you want to isolate a change within a repository |
+
+### How they work together
+
+In the fork workflow, you use all three:
+
+1. **Fork** the upstream repository to create your copy on GitHub
+2. **Clone** your fork to your computer
+3. **Create a branch** on your local clone for your specific change
+4. Push the branch to your fork and open a PR to the upstream
+
+```text
+Upstream repo (GitHub)      Your fork (GitHub)        Your computer (local)
++-------------------+       +-------------------+      +-------------------+
+| Community-Access/ |  fork | your-username/    | clone|                   |
+| accessibility-    | ----> | accessibility-    | ---> | accessibility-    |
+| agents            |       | agents            |      | agents            |
++-------------------+       +-------------------+      +-------------------+
+        ^                          ^                           |
+        |                          |                           |
+        +--- PR (fork to upstream) +--- git push              |
+                                                      edit, stage, commit
+```
+
+> **Screen reader note:** The text diagram above shows three boxes arranged left to right. The upstream repo on GitHub is on the left. Your fork on GitHub is in the middle. Your local computer is on the right. A fork arrow goes from left to middle. A clone arrow goes from middle to right. Editing happens on the right. Git push goes from right to middle. A PR goes from middle to left.
+
+### Learning Cards: Fork vs Clone vs Branch
+
+
    
+Screen reader users
+
+- Run `git remote -v` in the terminal to hear your configured remotes -- `origin` is your fork, `upstream` is the original repository
+- The Status Bar in VS Code shows the current branch name -- press `F6` to navigate there and confirm you are on a feature branch, not `main`
+- Use `Ctrl+Shift+P` then "Git: Checkout to" to switch between branches; your screen reader announces each branch name in the picker
+
+
    
+
+
    
+Low vision users
+
+- Your fork URL includes your username (e.g., `github.com/your-name/repo`) making it visually distinct from the upstream URL
+- In VS Code, the branch name in the bottom-left Status Bar confirms which branch you are working on -- zoom with `Ctrl+=` if it is too small
+- The Source Control panel heading shows the repository name to help you verify you are working in the correct clone
+
+
    
+
+
    
+Sighted users
+
+- On GitHub.com, forked repos show a "forked from" label under the repository name at the top of the page
+- The fork icon (a branching arrow) appears next to forked repository names in your GitHub profile
+- In VS Code, the bottom-left branch name and the Source Control panel header confirm your current branch and repository
+
+
    
+
+---
+
+## 3. Step 1: Fork the Repository
+
+### Tool Cards: Fork and Clone a Repository
+
+**github.com (browser):**
+1. Click **Fork** on the repository page > **Create fork**.
+2. Clone: click the green **Code** button > copy URL > paste into your local tool.
+
+**VS Code Desktop:**
+1. Fork on github.com first (browser required for forking).
+2. `Ctrl+Shift+P` > **Git: Clone** > paste your fork's URL.
+
+**GitHub Desktop:**
+1. Fork on github.com first.
+2. **File > Clone Repository** > select your fork from the GitHub.com tab.
+
+**GitHub CLI (one command):**
+```bash
+gh repo fork Community-Access/accessibility-agents --clone
+cd accessibility-agents
+```
+
+For this workshop, you will fork the [Community-Access/accessibility-agents](https://github.com/Community-Access/accessibility-agents) repository.
+
+### On GitHub.com
+
+1. Go to [github.com/Community-Access/accessibility-agents](https://github.com/Community-Access/accessibility-agents).
+2. Find the **Fork** button in the upper-right area of the page.
+   - **Screen reader users (NVDA/JAWS):** Press `B` to cycle through buttons. The Fork button is near the top of the page, after the Watch and Star buttons.
+   - **VoiceOver users:** Use `VO+U` to open the Buttons rotor and navigate to "Fork."
+3. GitHub shows a "Create a new fork" page. The defaults are correct:
+   - **Owner:** your username
+   - **Repository name:** `accessibility-agents`
+   - **Copy the main branch only:** checked (leave this checked)
+4. Activate **Create fork**.
+5. GitHub redirects you to your fork: `github.com/your-username/accessibility-agents`.
+
+You now have your own copy. The original repository at `Community-Access/accessibility-agents` is untouched.
+
+### Using GitHub CLI
+
+```bash
+gh repo fork Community-Access/accessibility-agents --clone=false
+```
+
+This creates the fork on GitHub without cloning it locally. We will clone in the next step.
+
+---
+
+## 4. Step 2: Clone Your Fork Locally
+
+Now download your fork to your computer so you can work on it.
+
+### Using VS Code
+
+1. Open VS Code.
+2. Open the command palette: `Ctrl+Shift+P` (or `Cmd+Shift+P`).
+3. Type "Git: Clone" and press `Enter`.
+4. Paste your fork URL: `https://github.com/your-username/accessibility-agents.git` (replace `your-username` with your GitHub username).
+5. Choose a folder (for example, `Documents`) and confirm.
+6. When the clone finishes, VS Code offers to open the repository. Accept.
+
+### Using the terminal
+
+```bash
+git clone https://github.com/your-username/accessibility-agents.git
+cd accessibility-agents
+```
+
+### Using GitHub Desktop
+
+1. Open GitHub Desktop.
+2. Go to File, then Clone repository.
+3. Select the **GitHub.com** tab and find `your-username/accessibility-agents`.
+4. Choose a local path and click Clone.
+
+### Using GitHub CLI
+
+```bash
+gh repo clone your-username/accessibility-agents
+cd accessibility-agents
+```
+
+After cloning, your local repository has one remote called `origin` that points to your fork.
+
+### Learning Cards: Cloning Your Fork
+
+
    
+Screen reader users
+
+- Use `Ctrl+Shift+P` then "Git: Clone" and paste your fork URL -- VS Code announces progress and opens the repository when done
+- After cloning, press `Ctrl+Shift+E` to open the Explorer and verify the file tree loaded correctly
+- Run `git remote -v` in the terminal (`Ctrl+\``) to confirm `origin` points to your fork URL
+
+
    
+
+
    
+Low vision users
+
+- After cloning, the Explorer sidebar populates with the repository files -- increase sidebar width by dragging its edge for better readability
+- The VS Code title bar shows the repository folder name, confirming which project is open
+- Use `Ctrl+P` to quick-open any file by name if the file tree is hard to navigate at high zoom
+
+
    
+
+
    
+Sighted users
+
+- After cloning, the Explorer sidebar shows the full file tree; the title bar displays the folder name
+- Look for the blue "Open Folder" notification or the repository name in the bottom Status Bar to confirm the clone succeeded
+- The Source Control panel (`Ctrl+Shift+G`) should show the repository with `main` as the current branch
+
+
    
+
+---
+
+## 5. Step 3: Add the Upstream Remote
+
+> **See also:** [Appendix E: Advanced Git](appendix-e-advanced-git.md) for advanced remote and upstream management.
+
+Your clone knows about your fork (`origin`). It does not know about the original repository. You need to add it as a second remote called `upstream`.
+
+### Why this matters
+
+Without the upstream remote, you cannot:
+
+- Pull new changes that other contributors make to the original repository
+- Keep your fork up to date
+- Verify your changes work with the latest code
+
+### Add the upstream remote
+
+```bash
+git remote add upstream https://github.com/Community-Access/accessibility-agents.git
+```
+
+### Verify your remotes
+
+```bash
+git remote -v
+```
+
+You should see:
+
+```text
+origin    https://github.com/your-username/accessibility-agents.git (fetch)
+origin    https://github.com/your-username/accessibility-agents.git (push)
+upstream  https://github.com/Community-Access/accessibility-agents.git (fetch)
+upstream  https://github.com/Community-Access/accessibility-agents.git (push)
+```
+
+Two remotes: `origin` (your fork) and `upstream` (the original).
+
+> **In VS Code:** You can also add the remote using the command palette. Press `Ctrl+Shift+P`, type "Git: Add Remote," enter `upstream` as the name, and paste the upstream URL.
+
+---
+
+## 6. Step 4: Create a Feature Branch
+
+Never work directly on the `main` branch of your fork. Always create a feature branch for each change. This keeps `main` clean and in sync with the upstream.
+
+### Create and switch to a new branch
+
+```bash
+git checkout -b agents/your-username-my-agent
+```
+
+The branch name `agents/your-username-my-agent` follows the workshop convention for Day 2 capstone branches. Replace `your-username` with your GitHub username and `my-agent` with a short name for your agent.
+
+### In VS Code
+
+1. Click the branch name in the bottom-left status bar (or press `Ctrl+Shift+P` and type "Git: Create Branch").
+2. Type the branch name: `agents/your-username-my-agent`.
+3. Press `Enter`. VS Code creates the branch and switches to it.
+
+### In GitHub Desktop
+
+1. Click the **Current Branch** dropdown.
+2. Click **New Branch**.
+3. Type the branch name and click **Create Branch**.
+
+### Verify you are on the new branch
+
+```bash
+git branch
+```
+
+The current branch has an asterisk (`*`) next to it.
+
+---
+
+## 7. Step 5: Make Your Changes
+
+Now you are on your feature branch and ready to work. For the capstone, you will create an agent file. For other contributions, you might edit documentation, fix a bug, or add a feature.
+
+### General principles for contributing
+
+- **Keep changes focused.** One branch, one purpose. If you want to make two unrelated changes, use two branches and two pull requests.
+- **Follow the project's conventions.** Look at existing files for patterns in naming, formatting, and structure.
+- **Write meaningful commit messages.** Describe what you changed and why. "Fix typo in README" is clear. "Update files" is not.
+
+### Stage and commit your changes
+
+After editing:
+
+```bash
+git add your-file.md
+git commit -m "Add my-agent accessibility agent"
+```
+
+Or stage all changed files:
+
+```bash
+git add .
+git commit -m "Add my-agent accessibility agent"
+```
+
+### In VS Code
+
+1. Open the Source Control panel: `Ctrl+Shift+G` (or `Cmd+Shift+G`).
+2. Changed files appear under "Changes." Click the `+` icon next to each file to stage it, or click `+` on the "Changes" header to stage all.
+   - **Screen reader users:** Navigate to the Source Control view. Each changed file is listed. Press `Enter` on a file to see the diff. Use the inline actions to stage.
+3. Type your commit message in the text field at the top.
+4. Press `Ctrl+Enter` (or `Cmd+Enter`) to commit.
+
+### Multiple commits are fine
+
+You do not need to make all your changes in a single commit. In fact, smaller commits are better because they are easier to review and easier to revert if something goes wrong.
+
+---
+
+## 8. Step 6: Push to Your Fork
+
+Your commits are saved locally. Now push them to your fork on GitHub.
+
+### First push (new branch)
+
+```bash
+git push -u origin agents/your-username-my-agent
+```
+
+The `-u` flag sets up tracking so future pushes from this branch go to the right place automatically.
+
+### Subsequent pushes
+
+```bash
+git push
+```
+
+### In VS Code
+
+After committing, the Source Control panel shows a **Sync Changes** button (or a cloud icon with an up arrow). Click it to push.
+
+Alternatively, use the command palette: `Ctrl+Shift+P`, type "Git: Push."
+
+### In GitHub Desktop
+
+After committing, click the **Push origin** button in the top bar.
+
+### Verify on GitHub
+
+After pushing, visit your fork on GitHub: `github.com/your-username/accessibility-agents`. You should see a banner saying "your-username-my-agent had recent pushes" with a **Compare and pull request** button.
+
+---
+
+## 9. Step 7: Open a Pull Request
+
+A pull request asks the upstream maintainers to merge your branch into their repository.
+
+### From the GitHub.com banner
+
+1. After pushing, GitHub shows a yellow banner on your fork with a **Compare and pull request** button. Click it.
+2. GitHub opens the "Open a pull request" page. Verify:
+   - **Base repository:** `Community-Access/accessibility-agents`
+   - **Base branch:** `main`
+   - **Head repository:** `your-username/accessibility-agents`
+   - **Compare branch:** `agents/your-username-my-agent`
+3. Write a descriptive title. Example: "Add document-contrast-checker agent."
+4. In the body, explain:
+   - What your change does
+   - Why it is useful
+   - Any testing you did
+   - Reference any related issues with `Closes #XX` if applicable
+5. If the project has a PR template, fill in all the required sections.
+6. Activate **Create pull request**.
+
+### From the Pull Requests tab
+
+1. Go to the upstream repository: [github.com/Community-Access/accessibility-agents](https://github.com/Community-Access/accessibility-agents).
+2. Click the **Pull requests** tab.
+3. Click **New pull request**.
+4. Click **compare across forks**.
+5. Set the head repository to your fork and the compare branch to your feature branch.
+6. Click **Create pull request** and fill in the details.
+
+### Using GitHub CLI
+
+```bash
+gh pr create --repo Community-Access/accessibility-agents --title "Add document-contrast-checker agent" --body "Description of what the agent does and why it is useful."
+```
+
+> **Screen reader tip:** The PR creation form is a standard web form. Navigate with `Tab` to move between fields. The title field and body field are `` and `